{"openapi":"3.0.0","info":{"title":"Fido External API","version":"1.0.0","description":"Fido's External API. Every endpoint here wraps the same controller the application itself uses, behind an API-key guard.\n\nAuthenticate with `Authorization: Bearer <api-key>`. Org and user tier keys must also send `X-Tenant-ID`.\n\nEach operation declares the key scope it requires as `x-fido-scope`, and the roles its underlying RBAC still enforces as `x-fido-roles`. A scope is `module:action` in the organization's own permission vocabulary — the modules and the read, write, edit and delete actions a role is configured with in Settings → Roles & Permissions. Where an operation accepts either of two scopes they are joined by `|`. `*`, `module:*` and `*:action` wildcards are accepted.\n\nScopes restrict a key; they do not replace role permissions, and both must pass."},"tags":[{"name":"Connectivity","description":"Check that a key works and see who it acts as. Any valid key can call these."},{"name":"Assignments"},{"name":"Shifts"},{"name":"Clients"},{"name":"Consumers"},{"name":"Providers"},{"name":"Check Ins"},{"name":"Schedule"},{"name":"Requests"},{"name":"Finances"},{"name":"Team"},{"name":"Handshakes"},{"name":"Forms"},{"name":"History & Logs"},{"name":"Settings · Assignments & Shifts"},{"name":"Settings · Broadcast & Dispatch Logic"},{"name":"Settings · General"},{"name":"Settings · Notifications & Preferences"},{"name":"Settings · Organization Locations"},{"name":"Settings · Preferred Users"},{"name":"Settings · Rates & Billing"},{"name":"Settings · Restricted Users"},{"name":"Settings · Service Setup"}],"paths":{"/v1/whoami":{"get":{"tags":["Connectivity"],"summary":"Identity and connectivity check","operationId":"ext_get_whoami","description":"Confirms the key resolves, and reports the user it acts as.\n\n**Exempt from the scope check** — any valid key may call this whatever scopes it holds, because the response contains only the caller's own identity and its own scope list. Authentication, expiry, the per-organization kill switch, IP allow-list, tenant pinning and rate limits all still apply.\n\nSend `X-Tenant-ID` for org and user tier keys; platform keys may omit it.","security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"responses":{"200":{"description":"The key is valid.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"user_id":{"type":"string","description":"The user the key acts as."},"name":{"type":"string","nullable":true},"tier":{"type":"string","enum":["platform","org","user"]},"role":{"type":"string","nullable":true,"description":"Role slug of the key owner, e.g. `super-admin`."},"scopes":{"type":"array","items":{"type":"string"},"example":["finance:read","finance:write"]},"tenant_id":{"type":"string","nullable":true,"description":"Echo of the X-Tenant-ID header as sent."}}}}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"x-fido-scope":"none:read","x-fido-module":"none","x-fido-roles":[],"x-fido-area":"Whoami","x-fido-area-rank":0}},"/v1/token-exchange":{"post":{"tags":["Connectivity"],"summary":"Exchange a platform key for an organization session token","operationId":"ext_post_token_exchange","description":"Signs in to one organization and returns a session token for it, for tooling that needs the in-app session rather than a key.\n\n**Platform tier and full access only.** The key must be platform tier and hold the `*` scope. A scoped key is refused, because the token carries every permission its target holds. The key owner must be a Super Admin or a Fido Service Provider; a Super Admin chooses the user to sign in as, a Fido Service Provider signs in as themselves.\n\n**Do not send `X-Tenant-ID`.** The organization is named in the body.\n\nThe token is a normal session: 24 hours, ending after 2 hours without use. Revoking the key does not end a session already issued. Every exchange is recorded in History & Logs against the real actor.","security":[{"apiKey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["organizationId"],"properties":{"organizationId":{"type":"string","description":"The organization to sign in to. It must be published.","example":"ORG-AB12CD34"},"userId":{"type":"string","nullable":true,"description":"Super Admin only: the organization user to sign in as. Defaults to the organization's admin.","example":"USR-AB12CD34"}}}}}},"responses":{"200":{"description":"Token issued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Token issued"},"data":{"type":"object","properties":{"token":{"type":"string","description":"Bearer token for the organization session."},"tenant_id":{"type":"string","example":"TNT-AB12CD34"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","nullable":true},"image":{"type":"string","nullable":true},"onlineStatus":{"type":"string"}}}}}}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The organization or the user was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"User not found in tenant"},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"x-fido-scope":"none:write","x-fido-module":"none","x-fido-roles":[],"x-fido-area":"Token exchange","x-fido-area-rank":1}},"/v1/assignments":{"get":{"tags":["Assignments"],"summary":"Retrieve a list of assignments","description":"**Required scope:** `assignments:read` or `shifts:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of assignments based on search criteria, filters, and sorting options. With isFromPortal=true the list also carries shifts (the Summary tab of a client, consumer or provider); a Scheduler or custom role needs Read on Assignments or Shifts (an API key the matching scope): assignments are left out without Assignments Read, shifts without Shifts Read, and without either the answer is an empty page.","operationId":"ext_get_assignments","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter assignmenr by name, email, or assignment Id.","required":false,"schema":{"type":"string","example":"assignment 1"}},{"name":"priority","in":"query","description":"Filter assignment by priority ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"status","in":"query","description":"Filter by assignment-status ID. Statuses are tenant-configurable rows, not a\n    fixed vocabulary, so there is no enum here — read the valid IDs for this tenant from\n    GET /assignment-statuses. A hard-coded value will go stale the moment a tenant edits its statuses.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"serviceTypes","in":"query","description":"Filter assignment by service Types ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"broadcast","in":"query","description":"Filter by broadcast state. Matched exactly against assignments.broadcast.","required":false,"schema":{"type":"string","enum":["off","active","onhold"],"example":"active"}},{"name":"serviceProvider","in":"query","description":"Filter assignment by service provider ID.","required":false,"schema":{"type":"string","example":"SRP-26TR5"}},{"name":"consumer","in":"query","description":"Filter assignment by consumer ID.","required":false,"schema":{"type":"string","example":"CSM-12FGT4"}},{"name":"client","in":"query","description":"Filter assignment by client ID.","required":false,"schema":{"type":"string","example":"CLT-567FGR"}},{"name":"isPublished","in":"query","description":"Filter assignments by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"without_active_invoice","in":"query","description":"when true, only assignments with no active (non-Canceled/Void) invoice link.","required":false,"schema":{"type":"boolean","example":true}},{"name":"without_active_payable","in":"query","description":"when true, only assignments with no active (non-Canceled/Void) payable link.","required":false,"schema":{"type":"boolean","example":true}},{"name":"sortBy","in":"query","description":"Sort clients by a specific field (e.g., 'name', 'created_at').","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of clients to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"columns","in":"query","description":"Search query within visible column content.","required":false,"schema":{"type":"string","example":"name,status,priority"}},{"name":"customTab","in":"query","description":"Preset filter tab, applied in addition to any other filters.","required":false,"schema":{"type":"string","enum":["active","archived","past","need_attention","upcoming","organization_request"],"example":"active"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter assignments by scheduled start date on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter assignments by scheduled end date on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"startTime","in":"query","required":false,"schema":{"description":"Filter assignments whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime; an overnight range (startTime later than endTime) is handled as spanning midnight.","type":"string","format":"time","example":null}},{"name":"endTime","in":"query","required":false,"schema":{"description":"Filter assignments whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","type":"string","format":"time","example":null}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"locationType","in":"query","description":"Filter by the Location column: the work item location type.","required":false,"schema":{"type":"string","enum":["onsite","remote","hybrid"],"example":"remote"}},{"name":"serviceProviderTypes","in":"query","description":"Filter by a provider type ID the work item asks for in its service-type breakdown (matches before anyone of that type is assigned).","required":false,"schema":{"type":"integer","example":3}},{"name":"requestSource","in":"query","description":"Filter by the Request Source column (origin of the request).","required":false,"schema":{"type":"string","enum":["client-portal","consumer-portal","scheduler","public-assistant"],"example":"client-portal"}},{"name":"updated_since","in":"query","description":"Only work items that changed at or after this moment: the assignment itself, any of its slots, any of its provider rows (assigned, removed or a status change) or any of its check-ins. Assignments deleted in the window are returned too, with `deletedAt` set, so the caller can drop them; canceled ones carry their status as usual. ISO 8601 date-time with a time zone (for example 2026-10-22T06:00:00Z) or a date (YYYY-MM-DD, taken as 00:00 UTC). A date-time with no zone is refused. The response `meta.asOf` is the moment the list was read; use it as the next `updated_since`. Keep the `meta.asOf` of the first page of a pull: every page reports its own, and the first one is the moment the pull began. Start each pull a few minutes before the previous `meta.asOf`: a change committed while a list was being read can carry a time just before it, and a row returned twice is harmless.","required":false,"schema":{"type":"string","example":"2026-10-22T06:00:00Z"}}],"responses":{"200":{"description":"Assignments retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"startDate":{"type":"string","example":"2026-01-15","nullable":true},"endDate":{"type":"string","example":"2026-01-15","nullable":true},"startTime":{"type":"string","example":"09:00:00","nullable":true},"endTime":{"type":"string","example":"09:00:00","nullable":true},"convertedStartDate":{"type":"string","example":"2026-01-15"},"convertedEndDate":{"type":"string","example":"2026-01-15"},"convertedStartTime":{"type":"string","example":"09:00:00"},"convertedEndTime":{"type":"string","example":"09:00:00"},"userTimezone":{"type":"string","example":"America/New_York","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"assignmentDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"userDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"requestedOn":{"type":"string","example":"2026-01-15"},"submissionDate":{"type":"string","example":"2026-01-15"},"timeSlots":{"properties":{"id":{"type":"integer","example":1},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"09:00:00"}},"type":"object","nullable":true},"deletedAt":{"description":"Only with updated_since: when the assignment was deleted (UTC, ending in Z), or empty while it exists.","type":"string","format":"date-time","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50},"asOf":{"description":"Only with updated_since: the moment the list was read; use it as the next updated_since. Take it from the first page of a pull; every page reports its own.","type":"string","format":"date-time","example":"2026-10-23T06:00:00Z"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"updated_since is not an ISO 8601 date-time with a time zone, or a date.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"type":"object","example":{"updated_since":["The updated_since must be an ISO 8601 date-time with a time zone (for example 2026-10-22T06:00:00Z) or a date (YYYY-MM-DD)."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read|shifts:read","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments","x-fido-area-rank":0},"post":{"tags":["Assignments"],"summary":"Create a new assignment","operationId":"ext_post_assignments","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"`required` lists only the fields required in every case. Most fields are conditionally required by isPublished, quickAssignment, assignTo and scheduleType.","required":["assignTo","scheduleType"],"properties":{"title":{"type":"string","example":"Special interpreter — intake appointment","nullable":true},"description":{"type":"string","example":"description of the assignment","nullable":true},"isPublished":{"description":"Publish immediately vs. save as a draft. Several other fields become required only when this is true.","type":"boolean","example":true},"quickAssignment":{"description":"The one-screen quick-create flow. Relaxes most other requirements in favor of quickServiceTypes/quickServiceProviderTypes and a same-day slot.","type":"boolean","example":false},"allowPointOfContact":{"description":"client_poc auto-fills requestor* from the client's primary location contact; the other values leave requestor* as sent.","type":"string","enum":["client_poc","external_contact","consumer","organization_poc"],"example":"client_poc"},"requestorName":{"type":"string","example":"John Doe","nullable":true},"requestorEmail":{"type":"string","format":"email","example":"user@example.com","nullable":true},"requestorPhone":{"type":"string","example":"1234567890","nullable":true},"requestorCountryCode":{"type":"string","example":"+1","nullable":true},"requestorPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"requestorPhoneExtension":{"type":"string","example":"123","nullable":true},"requestorConsumer":{"description":"The consumer the requestor is, when they are one of the assignment's own consumers rather than an outside party.","properties":{"id":{"type":"string","example":"CSM-SQEWP0T"}},"type":"object","nullable":true},"assignTo":{"type":"string","enum":["client","organization"],"example":"client"},"billTo":{"type":"string","enum":["organization","clients"],"example":"clients","nullable":true},"client":{"description":"Required when assignTo=client and newClient is not sent.","properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object","nullable":true},"newClient":{"description":"Creates a new client inline instead of using an existing one — alternative to client.","properties":{"name":{"type":"string","example":"Acme Corp"},"email":{"type":"string","format":"email","example":"contact@acme.test"},"contactName":{"type":"string","example":"Jane Roe"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"phoneExtension":{"type":"string","example":"123","nullable":true},"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"consumer":{"description":"Consumers on the assignment. A single object is also accepted and treated as a one-item list.","type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"},"label":{"type":"string","example":"Consumer Name"}},"type":"object"},"nullable":true},"newConsumer":{"description":"Creates a new consumer inline instead of using an existing one.","properties":{"name":{"type":"string","example":"Pat Doe"},"email":{"type":"string","format":"email","example":"pat@example.test","nullable":true},"phone":{"type":"string","example":"1234567890","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phoneExtension":{"type":"string","example":"123","nullable":true},"hearingStatus":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"preferredServiceLocations":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true}},"type":"object","nullable":true},"location":{"description":"Required (locationType) when isPublished=true. onsite/remote are read by locationType: onsite, remote, or both for hybrid.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"Also accepted at the top level as billingOrganizationLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"Also accepted at the top level as billingClientLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Defaults to primary. Also accepted at the top level as billingOption; the nested value wins if both are sent.","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"description":"Required when onSiteType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"description":"Required when onSiteType=client and newClient is not sent.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"description":"Required when onSiteType=manual.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"manualLocationContact":{"description":"Required when onSiteType=manual.","properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneExtension":{"type":"string","example":"123","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"description":"Required when onSiteType=ondemand.","type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"description":"Required when onDemandLocationType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"description":"Required when onDemandLocationType=client.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"description":"Required when onDemandLocationType=manual.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"onDemandManualLocationContact":{"properties":{"contactName":{"type":"string","example":"Jane Roe","nullable":true},"contactEmail":{"type":"string","format":"email","example":"jane@example.test","nullable":true},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"serviceTypes":{"description":"Required unless serviceTypeBreakdown is sent instead.","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"Per-service-type provider counts — alternative to serviceTypes when provider types are being split per service type.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"meetingPlatform":{"description":"Required when remoteType is not ondemand.","type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"billingOrganizationLocationId":{"type":"string","example":"1","nullable":true},"billingClientLocationId":{"type":"string","example":"1","nullable":true},"billingOption":{"type":"string","example":"primary","nullable":true},"timezone":{"type":"string","example":"America/New_York"},"scheduleType":{"type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring"},"oneTime":{"description":"Read only when scheduleType=one_time.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"multiDay":{"description":"Read only when scheduleType=multi_day.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"recurring":{"description":"Read only when scheduleType=recurring.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Priority Label"}},"type":"object","nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Status Label"}},"type":"object","nullable":true},"requestStatus":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Request Status Label"}},"type":"object","nullable":true},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object","nullable":true},"broadcast":{"properties":{"id":{"type":"string","example":"on"},"label":{"type":"string","example":"On"}},"type":"object","nullable":true},"broadcastNotify":{"description":"Mutually exclusive with broadcastAudience; send only one.","type":"boolean","example":true,"nullable":true},"broadcastAudience":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"}},"type":"object"},"nullable":true},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the assignment","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client/consumer","nullable":true},"allowPartialCoverage":{"type":"boolean","example":true},"partialDuration":{"description":"Partial coverage windows (required when allowPartialCoverage is true)","type":"array","items":{"properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-01"},"startTime":{"type":"string","example":"09:00"},"endTime":{"type":"string","example":"10:00"}},"type":"object"},"nullable":true},"assignmentMethod":{"type":"string","enum":["direct","accept","interest"],"example":"direct","nullable":true},"enableBroadcastBestMatch":{"description":"When true, a direct assignmentMethod no longer requires assignProviders — the best-match broadcast picks providers instead.","type":"boolean","example":true},"assignProviders":{"description":"Required when assignmentMethod=direct and enableBroadcastBestMatch is false.","type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"serviceType":{"type":"integer","example":1},"locationType":{"type":"string","enum":["onsite","remote"],"example":"onsite"},"serviceProviderType":{"description":"Provider type the provider fills. Inferred when the service type has only one.","type":"integer","example":2,"nullable":true},"partialReason":{"description":"Why a partly matching provider was assigned anyway.","type":"string","nullable":true},"notAvailableReason":{"description":"Why an unavailable provider was assigned anyway.","type":"string","nullable":true},"visibilityReason":{"description":"How the provider came to be listed. Defaults to partial_match_allowed when partialReason is sent, else full_match.","type":"string","example":"client_selected","nullable":true}},"type":"object"},"nullable":true},"overrideSingleRate":{"type":"boolean","example":true},"overrideBufferTime":{"type":"boolean","example":true},"overrideClientPreference":{"type":"boolean","example":true},"clientPreferences":{"description":"Which of the client's stored requirements and preferences the scheduler overrode on this work item. Each flag set to true means that kind is overridden. Stored as sent.","properties":{"clearance":{"type":"boolean","nullable":true},"skill":{"type":"boolean","nullable":true},"certifications":{"type":"boolean","nullable":true},"specialization":{"type":"boolean","nullable":true},"gender":{"type":"boolean","nullable":true},"restrictedServiceProvider":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"preferredServiceProvider":{"type":"boolean","nullable":true}},"type":"object"},"overrideConsumerPreferences":{"type":"boolean","example":true},"consumerPreferences":{"description":"The same override flags for the consumer's stored requirements and preferences. Stored as sent.","properties":{"clearance":{"type":"boolean","nullable":true},"skill":{"type":"boolean","nullable":true},"certifications":{"type":"boolean","nullable":true},"specialization":{"type":"boolean","nullable":true},"gender":{"type":"boolean","nullable":true},"restrictedServiceProvider":{"type":"boolean","nullable":true},"restrictedClients":{"type":"boolean","nullable":true},"preferredServiceProvider":{"type":"boolean","nullable":true}},"type":"object"},"overrideServiceProviderPreference":{"type":"boolean","example":true},"serviceProviderPreferences":{"description":"Provider-side rules the scheduler overrode on this work item. Stored as sent.","properties":{"overrideBufferTime":{"type":"boolean","nullable":true},"onSite":{"type":"boolean","nullable":true},"remote":{"type":"boolean","nullable":true},"assignmentLimits":{"type":"boolean","nullable":true},"availability":{"type":"boolean","nullable":true},"locationDistance":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"restrictedClients":{"type":"boolean","nullable":true},"restrictedServiceProviders":{"type":"boolean","nullable":true},"preferredConsumers":{"type":"boolean","nullable":true},"preferredClients":{"type":"boolean","nullable":true},"preferredServiceProviders":{"type":"boolean","nullable":true}},"type":"object"},"requireVerifiedTimeDocumentation":{"description":"Providers must sign in/out with a verified time record — see assignment-shift/provider/check-in.","type":"boolean","example":false},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"},"nullable":true},"providerExpenses":{"description":"Provider expenses attached at creation.","type":"array","items":{"description":"Expenses for one provider on a work item. Only providers currently assigned to the work item are processed.","required":["providerId"],"properties":{"entityId":{"description":"Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved.","type":"string","example":"ASG-SA2IVL","nullable":true},"providerId":{"type":"string","example":"SPR-H6OUI3"},"expenses":{"type":"array","items":{"required":["name"],"properties":{"id":{"description":"Existing expense id to update; omit to create.","type":"integer","example":42,"nullable":true},"name":{"type":"string","example":"Parking"},"amount":{"type":"number","minimum":0.01,"example":12.5,"nullable":true},"expense":{"description":"Unit amount, multiplied by quantity.","type":"number","minimum":0.01,"example":12.5,"nullable":true},"quantity":{"type":"number","minimum":0.01,"example":1,"nullable":true},"billTo":{"type":"string","enum":["organization","client"],"example":"organization","nullable":true},"document":{"description":"Receipt: pdf, jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isDefault":{"type":"boolean","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom expense.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"nullable":true},"rate":{"description":"Required when reimbursement_basic is percentage.","type":"number","minimum":0,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}}},"type":"object"},"nullable":true},"invoiceStatus":{"properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"payStatus":{"properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"quickServiceTypes":{"description":"Required when quickAssignment is true.","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true},"quickServiceProviderTypes":{"description":"Required when quickAssignment is true.","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true},"estimatedCost":{"description":"Client-calculated rate preview, saved as the assignment's estimated cost.","type":"object","nullable":true},"cancellationDetails":{"description":"Why and at whose cost a work item was canceled. Required (cancellationReason, cancellationCausedBy) when the status moves to a Canceled status. Stored as a blob and returned in the same shape.","properties":{"cancellationReason":{"type":"string","example":"Client requested cancellation"},"cancellationCausedBy":{"description":"Who caused the cancellation, as a label or a {id, label} object.","oneOf":[{"type":"string","example":"client"},{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}]},"cancellationCausedByClient":{"description":"The client or clients responsible, when the cause is a client: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"cancellationCausedByProvider":{"description":"The provider or providers responsible, when the cause is a provider: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"billableForCancellation":{"type":"boolean","example":true},"billCancellationClient":{"description":"When billableForCancellation is true, at least one of billCancellationClient/payCancellationProvider must also be true.","type":"boolean","example":true},"payCancellationProvider":{"type":"boolean","example":false}},"type":"object"},"duration":{"description":"Hours.","type":"number","example":1.5,"nullable":true},"requirementAndPreferences":{"description":"Ignored when quickAssignment is true; the quick flow builds the rows from quickServiceTypes and quickServiceProviderTypes.","type":"array","items":{"description":"Requirements and preferences for one service type on a work item. Rows without serviceType.id are skipped; the list replaces what is stored.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderCertifications":{"description":"Provider type, optionally with a certification it must hold. Pairs that do not belong to the service type are skipped.","type":"array","items":{"properties":{"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certifications":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"skillLevel":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"clearances":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"genderPreference":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"isDuplicated":{"description":"Set when this create duplicates an existing assignment; records a duplication audit event instead of a plain create.","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The assignment being duplicated. Read only with isDuplicated=true.","type":"string","example":"ASG-SA2IVL","nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Custom field values submitted from a public embed form, keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"properties":{"id":{"description":"Existing document id — omit file when updating an existing document's metadata only.","type":"integer","nullable":true},"file":{"description":"Required unless id is sent.","type":"string","format":"binary"},"fileName":{"type":"string","example":"intake-form.pdf"}},"type":"object"},"nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Assignment created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment created successfully"},"data":{"properties":{"id":{"type":"string","example":"ASG-001"},"skippedProviders":{"description":"Only present when a requested provider could not be attached (location or service type not on the record, no provider type, slot full). The record is still created.","type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-ABC123"},"locationType":{"type":"string","example":"onsite"},"serviceType":{"type":"integer","example":1},"serviceProviderType":{"type":"integer","example":2,"nullable":true},"reason":{"type":"string","example":"slot_full_or_type_not_on_record"}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Assignment creation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:write","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `assignments:write`  \n**Roles:** admin, scheduler","x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/shifts":{"get":{"tags":["Shifts"],"summary":"Retrieve a list of shifts","description":"**Required scope:** `shifts:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of shifts based on search criteria, filters, and sorting options.","operationId":"ext_get_shifts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter assignmenr by name, email, or shift Id.","required":false,"schema":{"type":"string","example":"shift 1"}},{"name":"priority","in":"query","description":"Filter shift by priority ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"status","in":"query","description":"Filter shift by shift-status ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"serviceTypes","in":"query","description":"Filter shift by service Types ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"broadcast","in":"query","description":"Filter shift by braodcast status.","required":false,"schema":{"type":"string","example":"on"}},{"name":"serviceProvider","in":"query","description":"Filter shift by service provider ID.","required":false,"schema":{"type":"string","example":"SRP-26TR5"}},{"name":"locationType","in":"query","description":"Filter shift by location type.","required":false,"schema":{"type":"string","example":"onsite"}},{"name":"shiftBlock","in":"query","description":"Filter shift by shift block.","required":false,"schema":{"type":"integer","example":1}},{"name":"client","in":"query","description":"Filter shift by client ID.","required":false,"schema":{"type":"string","example":"CLT-567FGR"}},{"name":"isPublished","in":"query","description":"Filter shifts by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"without_active_invoice","in":"query","description":"when true, only shifts with no active (non-Canceled/Void) invoice link.","required":false,"schema":{"type":"boolean","example":true}},{"name":"without_active_payable","in":"query","description":"when true, only shifts with no active (non-Canceled/Void) payable link.","required":false,"schema":{"type":"boolean","example":true}},{"name":"sortBy","in":"query","description":"Sort clients by a specific field (e.g., 'name', 'created_at').","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of clients to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"columns","in":"query","description":"Search query within visible column content.","required":false,"schema":{"type":"string","example":"name,status,priority"}},{"name":"customTab","in":"query","description":"Preset filter tab, applied in addition to any other filters.","required":false,"schema":{"type":"string","enum":["active","past","need_attention"],"example":"active"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter clients created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter clients created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"startTime","in":"query","required":false,"schema":{"description":"Filter shifts whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime; an overnight range (startTime later than endTime) is handled as spanning midnight.","type":"string","format":"time","example":null}},{"name":"endTime","in":"query","required":false,"schema":{"description":"Filter shifts whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","type":"string","format":"time","example":null}},{"name":"localSearch","in":"query","description":"The table's own search box: matches only the columns named in `columns`. `search` is the global search.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"updated_since","in":"query","description":"Only work items that changed at or after this moment: the shift itself, any of its slots, any of its provider rows (assigned, removed or a status change) or any of its check-ins. Shifts deleted in the window are returned too, with `deletedAt` set, so the caller can drop them; canceled ones carry their status as usual. ISO 8601 date-time with a time zone (for example 2026-10-22T06:00:00Z) or a date (YYYY-MM-DD, taken as 00:00 UTC). A date-time with no zone is refused. The response `meta.asOf` is the moment the list was read; use it as the next `updated_since`. Keep the `meta.asOf` of the first page of a pull: every page reports its own, and the first one is the moment the pull began. Start each pull a few minutes before the previous `meta.asOf`: a change committed while a list was being read can carry a time just before it, and a row returned twice is harmless.","required":false,"schema":{"type":"string","example":"2026-10-22T06:00:00Z"}}],"responses":{"200":{"description":"Shifts retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"startDate":{"type":"string","example":"2026-01-15","nullable":true},"endDate":{"type":"string","example":"2026-01-15","nullable":true},"startTime":{"type":"string","example":"09:00:00","nullable":true},"endTime":{"type":"string","example":"09:00:00","nullable":true},"convertedStartDate":{"type":"string","example":"2026-01-15"},"convertedEndDate":{"type":"string","example":"2026-01-15"},"convertedStartTime":{"type":"string","example":"09:00:00"},"convertedEndTime":{"type":"string","example":"09:00:00"},"userTimezone":{"type":"string","example":"America/New_York","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"assignmentDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"userDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"requestedOn":{"type":"string","example":"2026-01-15"},"submissionDate":{"type":"string","example":"2026-01-15"},"timeSlots":{"properties":{"id":{"type":"integer","example":1},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"09:00:00"}},"type":"object","nullable":true},"deletedAt":{"description":"Only with updated_since: when the shift was deleted (UTC, ending in Z), or empty while it exists.","type":"string","format":"date-time","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50},"asOf":{"description":"Only with updated_since: the moment the list was read; use it as the next updated_since. Take it from the first page of a pull; every page reports its own.","type":"string","format":"date-time","example":"2026-10-23T06:00:00Z"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"updated_since is not an ISO 8601 date-time with a time zone, or a date.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"type":"object","example":{"updated_since":["The updated_since must be an ISO 8601 date-time with a time zone (for example 2026-10-22T06:00:00Z) or a date (YYYY-MM-DD)."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:read","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shifts","x-fido-area-rank":0},"post":{"tags":["Shifts"],"summary":"Create a new shift","operationId":"ext_post_shifts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Only status and shiftBlock are unconditionally required. isPublished=true additionally requires timezone, assignTo, broadcast, assignmentMethod, scheduleType, location.locationType and the slots under the matching schedule-type wrapper; client is required whenever assignTo=client. A draft (isPublished=false) can be saved with almost nothing else set.","required":["status","shiftBlock"],"properties":{"title":{"type":"string","example":"Weekend overnight coverage","nullable":true},"description":{"type":"string","example":"description of the shift","nullable":true},"isPublished":{"description":"false saves a draft and relaxes nearly every other requirement; true publishes and triggers status auto-update plus the published notifications.","type":"boolean","example":true,"nullable":true},"duration":{"description":"Hours — used when setting location.onsite/remote slot capacity.","type":"number","example":1.5,"nullable":true},"allowPointOfContact":{"description":"Any non-empty value auto-fills requestorEmail/requestorPhone from the client's primary location contact, overwriting whatever was sent.","type":"string","example":"client_poc","nullable":true},"requestorName":{"description":"Not validated; stored with the shift and shown in the list and sidebar.","type":"string","example":"John Doe","nullable":true},"requestorEmail":{"type":"string","format":"email","example":"user@example.com","nullable":true},"requestorPhone":{"type":"string","example":"1234567890","nullable":true},"requestorCountryCode":{"type":"string","example":"+1","nullable":true},"requestorPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"requestorPhoneExtension":{"type":"string","example":"123","nullable":true},"assignTo":{"description":"Prunes the payload before anything is stored: assignTo=client drops assignClient, assignTo=organization drops client — so a contradictory pair never reaches the relation handlers.","type":"string","enum":["client","organization"],"example":"client","nullable":true},"billTo":{"description":"clients (with a non-empty assignClients) switches the shift to per-client billing.","type":"string","enum":["organization","clients"],"example":"clients","nullable":true},"client":{"description":"The single client. Required when assignTo=client. Dropped outright when assignTo=organization, and ignored when assignClients/assignClient is sent in the same payload.","properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object","nullable":true},"assignClients":{"description":"The shift's full client roster. Not validated. Dropped outright when assignTo=client. assignClient (singular key, same array shape) is accepted as a legacy alias.","type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object"},"nullable":true},"assignClient":{"description":"Legacy alias for assignClients — same shape, same effect.","type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"}},"type":"object"},"nullable":true},"assignClientLocation":{"description":"Not validated. Sets the shift's client locations; assignments have no equivalent.","type":"array","items":{"properties":{"id":{"type":"string","example":"1"}},"type":"object"},"nullable":true},"billingDistribution":{"description":"How the shift's cost is divided across multiple clients. Only meaningful on a multi-client shift.","type":"string","enum":["split_evenly","manual_allocation","individual"],"example":"split_evenly","nullable":true},"clientAllocations":{"description":"Per-client service charges, read when billTo=clients. Not validated on create — unlike the update endpoint, there is no check that the charges sum to a declared total, and totalServiceCharge is not read here at all.","type":"array","items":{"properties":{"clientId":{"type":"string","example":"CLT-KBX0Q6"},"serviceCharges":{"type":"number","example":125.5}},"type":"object"},"nullable":true},"billingOption":{"description":"Top-level fallback for location.billingOption, which wins when both are sent. Defaults to primary. Unlike the shift update endpoint, this top-level form IS read on create.","type":"string","example":"primary","nullable":true},"location":{"description":"locationType is required when isPublished=true.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"A {id} object is also accepted. Nested here only — there is no top-level fallback for this one.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"A {id} object is also accepted. Nested here only — there is no top-level fallback for this one.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Wins over the top-level billingOption.","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"manualLocationContact":{"description":"contactPhone is required (when published) unless videoPhone is sent. The server derives fullManuallyContactPhone/fullManuallyContactVideoPhone from these sub-fields — those two are output, not accepted input.","properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneExtension":{"type":"string","example":"123","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"The sum of providerTypeBreakdown.totalProviders must equal totalProviders.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"meetingPlatform":{"type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"timezone":{"description":"Required when isPublished=true. Defaults to the organization's timezone when omitted.","type":"string","example":"America/New_York","nullable":true},"scheduleType":{"description":"Selects which wrapper below the slots are read from; an unrecognized value is rejected.","type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring","nullable":true},"oneTime":{"description":"Read only when scheduleType=one_time.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"multiDay":{"description":"Read only when scheduleType=multi_day.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"recurring":{"description":"Read only when scheduleType=recurring.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Priority Label"}},"type":"object","nullable":true},"status":{"description":"Required. Send {id} alone and the label is filled from the statuses table. Omit the id and the status defaults to Still Seeking when publishing, On Hold when saving a draft.","properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Status Label","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object","nullable":true},"shiftBlock":{"description":"Required — a shift is always created inside a shift block, which an assignment has no equivalent of.","properties":{"id":{"type":"integer","example":1}},"type":"object"},"broadcast":{"description":"Required when isPublished=true.","properties":{"id":{"type":"string","example":"on"},"label":{"type":"string","example":"On"}},"type":"object","nullable":true},"broadcastNotify":{"type":"boolean","example":true,"nullable":true},"broadcastAudience":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"}},"type":"object"},"nullable":true},"enableBroadcastBestMatch":{"description":"When true, assignProviders is no longer required for a published direct shift.","type":"boolean","example":true,"nullable":true},"assignmentMethod":{"description":"Required when isPublished=true.","type":"string","enum":["direct","accept","interest"],"example":"direct","nullable":true},"assignProviders":{"description":"Required for a published direct shift unless enableBroadcastBestMatch is true. A provider that cannot be attached is reported back in data.skippedProviders rather than failing the create.","type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"serviceType":{"type":"integer","example":1},"locationType":{"type":"string","enum":["onsite","remote"],"example":"onsite"},"serviceProviderType":{"description":"Provider type the provider fills. Inferred when the service type has only one.","type":"integer","example":2,"nullable":true},"partialReason":{"description":"Why a partly matching provider was assigned anyway.","type":"string","nullable":true},"notAvailableReason":{"description":"Why an unavailable provider was assigned anyway.","type":"string","nullable":true},"visibilityReason":{"description":"How the provider came to be listed. Defaults to partial_match_allowed when partialReason is sent, else full_match.","type":"string","example":"client_selected","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"requirementAndPreferences":{"description":"Not validated; saved as the shift's requirements and preferences.","type":"array","items":{"properties":{"serviceType":{"type":"integer","example":1},"serviceProviderCertifications":{"description":"Required when serviceType is set.","type":"array","items":{"properties":{"serviceProviderType":{"type":"integer","example":1}},"type":"object"}}},"type":"object"},"nullable":true},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the shift","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client","nullable":true},"allowPartialCoverage":{"type":"boolean","example":true,"nullable":true},"partialDuration":{"description":"Partial coverage windows — required when allowPartialCoverage is true.","type":"array","items":{"properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-01"},"startTime":{"type":"string","example":"09:00"},"endTime":{"type":"string","example":"10:00"}},"type":"object"},"nullable":true},"overrideSingleRate":{"type":"boolean","example":true,"nullable":true},"overrideBufferTime":{"type":"boolean","example":true,"nullable":true},"overrideClientPreference":{"type":"boolean","example":true,"nullable":true},"clientPreferences":{"description":"Which of the client's stored requirements and preferences the scheduler overrode on this work item. Each flag set to true means that kind is overridden. Stored as sent.","properties":{"clearance":{"type":"boolean","nullable":true},"skill":{"type":"boolean","nullable":true},"certifications":{"type":"boolean","nullable":true},"specialization":{"type":"boolean","nullable":true},"gender":{"type":"boolean","nullable":true},"restrictedServiceProvider":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"preferredServiceProvider":{"type":"boolean","nullable":true}},"type":"object"},"overrideServiceProviderPreference":{"type":"boolean","example":true,"nullable":true},"serviceProviderPreferences":{"description":"Provider-side rules the scheduler overrode on this work item. Stored as sent.","properties":{"overrideBufferTime":{"type":"boolean","nullable":true},"onSite":{"type":"boolean","nullable":true},"remote":{"type":"boolean","nullable":true},"assignmentLimits":{"type":"boolean","nullable":true},"availability":{"type":"boolean","nullable":true},"locationDistance":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"restrictedClients":{"type":"boolean","nullable":true},"restrictedServiceProviders":{"type":"boolean","nullable":true},"preferredConsumers":{"type":"boolean","nullable":true},"preferredClients":{"type":"boolean","nullable":true},"preferredServiceProviders":{"type":"boolean","nullable":true}},"type":"object"},"requireVerifiedTimeDocumentation":{"type":"boolean","example":false,"nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"},"nullable":true},"providerExpenses":{"description":"Provider expenses.","type":"array","items":{"description":"Expenses for one provider on a work item. Only providers currently assigned to the work item are processed.","required":["providerId"],"properties":{"entityId":{"description":"Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved.","type":"string","example":"ASG-SA2IVL","nullable":true},"providerId":{"type":"string","example":"SPR-H6OUI3"},"expenses":{"type":"array","items":{"required":["name"],"properties":{"id":{"description":"Existing expense id to update; omit to create.","type":"integer","example":42,"nullable":true},"name":{"type":"string","example":"Parking"},"amount":{"type":"number","minimum":0.01,"example":12.5,"nullable":true},"expense":{"description":"Unit amount, multiplied by quantity.","type":"number","minimum":0.01,"example":12.5,"nullable":true},"quantity":{"type":"number","minimum":0.01,"example":1,"nullable":true},"billTo":{"type":"string","enum":["organization","client"],"example":"organization","nullable":true},"document":{"description":"Receipt: pdf, jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isDefault":{"type":"boolean","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom expense.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"nullable":true},"rate":{"description":"Required when reimbursement_basic is percentage.","type":"number","minimum":0,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}}},"type":"object"},"nullable":true},"invoiceStatus":{"description":"Only stored when billing is enabled for shifts and the status is a completed one; otherwise cleared.","properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"payStatus":{"description":"Only stored when payables are enabled for shifts and the status is a completed one; otherwise cleared.","properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"estimatedCost":{"description":"Client-calculated rate preview.","type":"object","nullable":true},"isDuplicated":{"description":"Set when this create duplicates an existing shift; records a duplication audit event instead of a plain create.","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The shift being duplicated. Read only with isDuplicated=true.","type":"string","example":"SFT-K2L9QX","nullable":true},"customFields":{"description":"Custom field values keyed by field id. File-typed values are attached once the shift exists.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"properties":{"file":{"type":"string","format":"binary"},"fileName":{"type":"string","example":"intake-form.pdf"}},"type":"object"},"nullable":true},"cancellationDetails":{"description":"Only meaningful when creating a shift directly in a canceled status. cancellationReason/cancellationCausedBy/billableForCancellation/billCancellationClient/payCancellationProvider are also accepted flat at the top level; the nested value wins if both are sent.","properties":{"cancellationReason":{"type":"string","example":"Client requested cancellation"},"cancellationCausedBy":{"description":"Who caused the cancellation, as a label or a {id, label} object.","oneOf":[{"type":"string","example":"client"},{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}]},"cancellationCausedByClient":{"description":"The client or clients responsible, when the cause is a client: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"cancellationCausedByProvider":{"description":"The provider or providers responsible, when the cause is a provider: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"billableForCancellation":{"type":"boolean","example":true},"billCancellationClient":{"description":"When billableForCancellation is true, at least one of billCancellationClient/payCancellationProvider must also be true.","type":"boolean","example":true},"payCancellationProvider":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"responses":{"201":{"description":"Shift created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift created successfully"},"data":{"properties":{"id":{"description":"The new shift's id — shifts are prefixed SFT-, not ASG-.","type":"string","example":"SFT-MNP4PJ"},"skippedProviders":{"description":"Only present when a requested provider could not be attached (location or service type not on the record, no provider type, slot full). The record is still created.","type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-ABC123"},"locationType":{"type":"string","example":"onsite"},"serviceType":{"type":"integer","example":1},"serviceProviderType":{"type":"integer","example":2,"nullable":true},"reason":{"type":"string","example":"slot_full_or_type_not_on_record"}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Shift creation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:write","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `shifts:write`  \n**Roles:** admin, scheduler","x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/clients":{"get":{"tags":["Clients"],"summary":"Retrieve a list of clients","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of clients based on search criteria, filters, and sorting options.","operationId":"ext_get_clients","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter clients by name, email, or client_id.","required":false,"schema":{"type":"string","example":"acme"}},{"name":"priority","in":"query","description":"Filter clients by priority ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"status","in":"query","description":"Filter clients by status ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"portalAccess","in":"query","description":"Filter clients by their Portal Access status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"inviteState","in":"query","description":"Filter by the Invite State column, using the same rule as the inviteState badge.","required":false,"schema":{"type":"string","enum":["invited","invite_expired","active","active_never_signed_in","not_invited"],"example":"invite_expired"}},{"name":"isPublished","in":"query","description":"Filter clients by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"sortBy","in":"query","description":"Sort clients by a specific field (e.g., 'clientName', 'created_at').","required":false,"schema":{"type":"string","example":"clientName"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of clients to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"columns","in":"query","description":"Search query within visible column content.","required":false,"schema":{"type":"string","example":"clientName,address,contact,status"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter clients created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter clients created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"localSearch","in":"query","description":"The table's own search box: matches only the columns named in `columns`. `search` is the global search.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Clients retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-XWB2RY"},"name":{"type":"string","example":"Example name","nullable":true},"onlineStatus":{"type":"string","example":"online"},"email":{"type":"string","example":"user@example.com","nullable":true},"logo":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"phone":{"type":"string","example":"+1-555-0142","nullable":true},"portalAccess":{"type":"boolean","example":true},"canLogin":{"type":"boolean","example":true},"inviteState":{"type":"string","enum":["invited","invite_expired","active","active_never_signed_in","not_invited"],"example":"invited"},"inviteExpiresAt":{"description":"When the invite link expires or expired; null when there is no invite link","type":"string","format":"date-time","nullable":true},"status":{"type":"integer","example":1,"nullable":true},"statusName":{"type":"string","example":"Active","nullable":true},"priority":{"type":"integer","example":1,"nullable":true},"priorityName":{"type":"string","example":"Example name","nullable":true},"isPublished":{"type":"boolean","example":true},"addressLine1":{"type":"string","example":"123 Main St","nullable":true},"addressLine2":{"type":"string","example":"Suite 200","nullable":true},"city":{"type":"string","example":"Austin","nullable":true},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","example":"90210","nullable":true},"contactName":{"type":"string","example":"Jane Smith","nullable":true},"contactEmail":{"type":"string","example":"user@example.com","nullable":true},"contactPhone":{"type":"string","example":"+1-555-0142","nullable":true},"contactPhoneExtension":{"type":"string","example":"101","nullable":true},"contactImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"activeAssignments":{"description":"Count of active assignments and shifts linked to the client","type":"integer","example":3},"lastAssignmentDate":{"description":"Latest start date across the client's active assignments and shifts","type":"string","format":"date","example":"2026-08-21","nullable":true},"statusChangedAt":{"description":"When the client entered its current status","type":"string","format":"date-time","example":"2026-06-30 14:29:07","nullable":true},"publishedAt":{"description":"When the client entered its current publication state","type":"string","format":"date-time","example":"2026-06-30 14:29:07","nullable":true},"gender":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"hearingStatus":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"industry":{"type":"array","items":[],"nullable":true},"requiresPrimaryReassignmentOnDelete":{"type":"string"},"otherActiveRoles":{"type":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clients","x-fido-area-rank":0},"post":{"tags":["Clients"],"summary":"Create a new client","description":"**Required scope:** `clients:write`  \n**Roles:** admin, scheduler\n\nCreates a new client with associated preferences, documents, billing, and other details. Rates & Billing fields (rates, single rates, admin fee, billing and cancellation terms) need Finance Write: without it they are left out and the new record takes the organization's.","operationId":"ext_post_clients","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"tenant_123"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Sent as multipart/form-data when a logo, contact image or document is attached; nested objects and lists may then be JSON-encoded strings.","required":["name","clientType"],"properties":{"name":{"type":"string","maxLength":255,"example":"Acme Health"},"clientType":{"description":"Required on create.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"email":{"description":"Required when portalAccess or networkAccess is true. Unique among clients.","type":"string","format":"email","maxLength":255,"example":"ops@acme.test","nullable":true},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"portalAccess":{"description":"Let the client sign in to the client portal.","type":"boolean","example":false,"nullable":true},"networkAccess":{"description":"Share the client with the Fido network.","type":"boolean","example":false,"nullable":true},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"formId":{"description":"Intake form the client came from.","type":"string","nullable":true},"industry":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"hearingStatus":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateOfBirth":{"type":"string","format":"date","nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"enableCalendarIntegration":{"type":"boolean","nullable":true},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"phoneExtension":{"type":"string","maxLength":10,"example":"204","nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"addressLine1":{"description":"Primary location address.","type":"string","maxLength":255,"example":"123 Main St.","nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"type":"string","maxLength":100,"example":"Dover","nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"12345 or 12345-6789.","type":"string","example":"19901","nullable":true},"accessInstruction":{"type":"string","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"shiftCapacity":{"type":"boolean","example":false,"nullable":true},"minimumCapacity":{"description":"Required when shiftCapacity is true; at most maximumCapacity.","type":"integer","minimum":0,"nullable":true},"maximumCapacity":{"description":"Required when shiftCapacity is true; at least minimumCapacity.","type":"integer","minimum":1,"nullable":true},"billingAddressDifferent":{"type":"boolean","nullable":true},"billingStreetAddress":{"type":"string","nullable":true},"billingStreetAddressLine2":{"type":"string","nullable":true},"billingCity":{"type":"string","nullable":true},"billingState":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billingPostalCode":{"type":"string","nullable":true},"department":{"description":"Primary location contact.","type":"string","maxLength":255,"nullable":true},"contactName":{"type":"string","maxLength":255,"nullable":true},"role":{"type":"string","maxLength":255,"nullable":true},"contactEmail":{"type":"string","format":"email","maxLength":255,"nullable":true},"contactImage":{"description":"jpg, jpeg, png or gif, max 2 MB.","type":"string","format":"binary","nullable":true},"contactPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhone":{"description":"Required when receiveSms is true.","type":"string","nullable":true},"contactPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"contactPhoneExtension":{"type":"string","nullable":true},"contactVideoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"contactVideoPhone":{"type":"string","nullable":true},"assignmentRequest":{"description":"Notification preference.","type":"boolean","nullable":true},"assignmentUpdates":{"description":"Notification preference.","type":"boolean","nullable":true},"allowClientsToBroadcastImmediately":{"description":"The client's requests broadcast without scheduler review.","type":"boolean","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"defaultTimezone":{"description":"Localization.","type":"string","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization.","type":"string","nullable":true},"startOfWeek":{"description":"Localization.","type":"string","example":"monday","nullable":true},"startOfDay":{"description":"Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"Localization.","type":"string","example":"18:00","nullable":true},"preferredServiceLocations":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"associatedConsumer":{"description":"Consumers associated with the client.","type":"array","items":{"properties":{"consumer":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"relationship":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"portalAccess":{"type":"boolean","nullable":true},"allowServiceRequests":{"type":"boolean","nullable":true},"allowAssignmentChanges":{"type":"boolean","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userPreferred":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"customizeRequirementPreferences":{"description":"Per-service-type requirements. true reads requirementAndPreferences; false reads the flat default-tier fields below.","type":"boolean","nullable":true},"serviceTypes":{"description":"Default requirement tier. Service types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderTypes":{"description":"Default requirement tier. Provider roles.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"providerTypes":{"description":"Default requirement tier. Provider types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"description":"Default requirement tier. Minimum skill level.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"genderPreferences":{"description":"Default requirement tier. Preferred provider gender.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"certifications":{"description":"Default requirement tier. Required certifications.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"clearances":{"description":"Default requirement tier. Required clearances.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"specializations":{"description":"Default requirement tier. Required specializations.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedClients":{"description":"Clients this client may not be scheduled with.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientRestricted":{"description":"Client users restricted from this client.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientLocation":{"description":"Existing client location to attach this client to.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]}},"type":"object","nullable":true},"expenses":{"description":"Reimbursable expense categories enabled for this client.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"requirementAndPreferences":{"type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customizeRateBilling":{"description":"Use the client's own rates and billing instead of the organization defaults. Makes billingFrequency and invoiceFrequency required.","type":"boolean","nullable":true},"adminFee":{"type":"number","nullable":true},"adminFeeMethod":{"type":"string","example":"flat","nullable":true},"adminFeeType":{"type":"string","enum":["assignment","shift","both"],"nullable":true},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"},"nullable":true},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"},"nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"applyCancellationFee":{"type":"boolean","nullable":true},"feeType":{"description":"Required when applyCancellationFee is true. full clears feeValue.","type":"string","enum":["full","flat","percentage"],"nullable":true},"feeValue":{"type":"number","minimum":0,"nullable":true},"cancellationWindow":{"description":"Required when applyCancellationFee is true.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"paymentTerm":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"autoGenerateInvoice":{"type":"boolean","nullable":true},"autoSendInvoice":{"type":"boolean","nullable":true},"autoGenerateProForma":{"type":"boolean","nullable":true},"autoSendProForma":{"type":"boolean","nullable":true},"billingFrequency":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"invoiceFrequency":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"proFormaGroupsPerCycle":{"description":"Required with billingFrequency or invoiceFrequency.","type":"integer","maximum":12,"minimum":1,"nullable":true},"beginBillingSchedule":{"description":"Required with billingFrequency or invoiceFrequency.","type":"string","format":"date","nullable":true},"invoiceSendDay":{"description":"Required with billingFrequency or invoiceFrequency.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"proFormaSendSchedule":{"description":"Required with billingFrequency or invoiceFrequency.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"billingResponsibility":{"type":"string","nullable":true},"expenseApprovalAccess":{"type":"boolean","nullable":true},"requireVerifiedTimeDocumentation":{"type":"boolean","nullable":true},"documents":{"description":"pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each.","type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"isDuplicated":{"description":"Set when this create duplicates an existing client; records a duplication audit event instead of a plain create.","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The client being duplicated. Read only with isDuplicated=true.","type":"string","example":"CLT-KBX0Q6","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Client created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client created successfully"},"data":{"properties":{"id":{"type":"string","example":"CLT-101"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Client created successfully","data":{"id":"CLT-101"}}}}},"401":{"description":"Unauthorized - Token required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"The name field is required."}},"clientType":{"type":"array","items":{"type":"string","example":"The clientType field is required."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation failed","errors":{"name":["The name field is required."],"clientType":["The clientType field is required."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:write","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clients","x-fido-area-rank":0}},"/v1/consumers":{"get":{"tags":["Consumers"],"summary":"Retrieve a list of consumers","description":"**Required scope:** `consumers:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of consumers based on filters, search criteria, and sorting options.","operationId":"ext_get_consumers","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search consumers by name, email, or consumer ID.","required":false,"schema":{"type":"string"}},{"name":"serviceTypes","in":"query","description":"Comma-separated list of service type IDs.","required":false,"schema":{"type":"string"}},{"name":"hearingStatus","in":"query","description":"Hearing status filter.","required":false,"schema":{"type":"string"}},{"name":"isPublished","in":"query","description":"Filter consumers by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"needsReview","in":"query","description":"Only consumers whose guardianship review is open (turned 18 with guardians still acting, pending or snoozed).","required":false,"schema":{"type":"boolean","example":true}},{"name":"communicationModes","in":"query","description":"Comma-separated list of communication mode IDs.","required":false,"schema":{"type":"string"}},{"name":"associatedClient","in":"query","description":"Comma-separated list of client IDs associated with the consumer.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by status ID.","required":false,"schema":{"type":"integer"}},{"name":"priority","in":"query","description":"Filter by priority ID.","required":false,"schema":{"type":"integer"}},{"name":"startDate","in":"query","description":"Start date for filtering consumers (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for filtering consumers (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"sortBy","in":"query","description":"Field to sort by (e.g., 'user', 'priority', 'created_at').","required":false,"schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Number of records per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"columns","in":"query","description":"Comma-separated list of columns for filtering or display. Valid columns: user, status, priority, serviceTypes, hearingStatus, communicationModes, associatedClient.","required":false,"schema":{"type":"string","example":"user, status, priority, serviceTypes, hearingStatus, communicationModes, associatedClient"}},{"name":"portalAccess","in":"query","description":"Filter by the Portal Access column.","required":false,"schema":{"type":"boolean","example":true}},{"name":"inviteState","in":"query","description":"Filter by the Invite State column, using the same rule as the inviteState badge.","required":false,"schema":{"type":"string","enum":["invited","invite_expired","active","active_never_signed_in","not_invited"],"example":"invite_expired"}}],"responses":{"200":{"description":"Consumers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"name":{"type":"string","example":"Example name","nullable":true},"onlineStatus":{"type":"string","example":"online"},"email":{"type":"string","example":"user@example.com","nullable":true},"phone":{"type":"string","example":"+1-555-0142","nullable":true},"logo":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"status":{"type":"integer","example":1,"nullable":true},"statusName":{"type":"string","example":"Active","nullable":true},"statusChangedAt":{"description":"When the consumer entered its current status","type":"string","format":"date-time","example":"2026-06-30 14:29:00","nullable":true},"publishedAt":{"description":"When the consumer entered its current publication state","type":"string","format":"date-time","example":"2026-06-30 14:29:00","nullable":true},"priority":{"type":"integer","example":1,"nullable":true},"priorityName":{"type":"string","example":"Example name","nullable":true},"associatedClient":{"type":"array","items":{"properties":{"client":{"type":"string","example":"CLT-PJ6TFP"},"clientName":{"type":"string","example":"Test2"},"clientImage":{"type":"string","example":"hi"},"relationship":{"type":"string","example":"employee"}},"type":"object"}},"serviceTypes":{"type":"array","items":{"type":"integer","example":6}},"serviceTypesName":{"type":"array","items":{"type":"string"}},"hearingStatus":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"communicationModes":{"type":"array","items":{"type":"integer","example":1}},"communicationModesName":{"type":"array","items":{"type":"string","example":"ASL (American Sign Language)"}},"portalAccess":{"type":"boolean","example":true},"canLogin":{"type":"boolean","example":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"activeAssignment":{"type":"integer","example":1},"gender":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"requiresPrimaryReassignmentOnDelete":{"type":"string"},"otherActiveRoles":{"type":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid filters provided. Please check the query parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Token missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Consumers","x-fido-area-rank":0},"post":{"tags":["Consumers"],"summary":"Create a new consumer","operationId":"ext_post_consumers","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for the request","required":true,"schema":{"type":"string","example":"TNT-97MD3QAU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"An organization consumer, as the create and update forms send it. Sent as multipart/form-data when a logo or document is attached; nested objects and lists may then be JSON-encoded strings. Fields marked 'required when published' are required only with isPublished=true; a draft (isPublished=false) gets the Pending status, the Deaf hearing status and the ASL communication mode when those are omitted.","required":["name","portalAccess"],"properties":{"name":{"type":"string","maxLength":255,"example":"Pat Doe"},"email":{"description":"Required when portalAccess, networkAccess or receiveEmail is true. Unique among this organization's users, and in the network when networkAccess is true.","type":"string","format":"email","maxLength":255,"example":"pat@example.test","nullable":true},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"dateOfBirth":{"description":"Under 18 makes the consumer a minor; a new minor needs a guardian or the independent-minor acknowledgment","type":"string","format":"date","example":"2014-05-01","nullable":true},"hasLegalGuardian":{"description":"Guardians act for this consumer whatever their age. Omit to leave as stored","type":"boolean","nullable":true},"independentMinorAck":{"description":"A minor deliberately with no guardian; needs independentMinorReason","type":"boolean","nullable":true},"independentMinorReason":{"type":"string","maxLength":255,"nullable":true},"notifyMinorToo":{"description":"Under guardianship, the consumer also receives their own notifications","type":"boolean","nullable":true},"guardians":{"description":"Replaces the consumer's guardian links when sent (a JSON string on multipart). Omit to leave them as they are","type":"array","items":{"$ref":"#/components/schemas/GuardianInput"},"nullable":true},"gender":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"phoneExtension":{"type":"string","maxLength":10,"example":"204","nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"addressLine1":{"type":"string","maxLength":255,"example":"101 Street","nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"type":"string","maxLength":100,"example":"Austin","nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"12345 or 12345-6789.","type":"string","example":"78759","nullable":true},"status":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"consumerType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"hearingStatus":{"description":"Required when published. id is a hearing-status value such as deaf.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"communicationModes":{"description":"Required when published.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"portalAccess":{"description":"Let the consumer sign in to the consumer portal. Defaults to the organization's auto-populate setting.","type":"boolean","example":false},"networkAccess":{"description":"Share the consumer with the Fido network.","type":"boolean","example":false,"nullable":true},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"enableCalendarIntegration":{"type":"boolean","nullable":true},"assignmentUpdates":{"description":"Notification preference.","type":"boolean","nullable":true},"serviceReminders":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"profileShareWithinOrganization":{"type":"boolean","nullable":true},"defaultTimezone":{"description":"Localization. Required when published.","type":"string","example":"America/Chicago","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization. Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization. Required when published.","type":"string","nullable":true},"startOfWeek":{"description":"Localization. Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startOfDay":{"description":"Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"Localization.","type":"string","example":"18:00","nullable":true},"preferredServiceLocations":{"description":"Required when published. id is onsite, remote or both.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"associatedClient":{"description":"Clients the consumer is associated with. Required when published. A client left out of an update is detached.","type":"array","items":{"properties":{"client":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"relationship":{"description":"Omit to keep the stored relationship; send null to clear it.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"allowPortalAccess":{"type":"boolean","nullable":true},"allowServiceRequests":{"type":"boolean","nullable":true},"allowAssignmentChanges":{"type":"boolean","nullable":true}},"type":"object"},"nullable":true},"userPreferred":{"description":"Preferred providers. Must not overlap userRestricted.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"description":"Restricted providers.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientRestricted":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"customizeRequirementPreferences":{"description":"Per-service-type requirements. true reads requirementAndPreferences; false reads the flat default-tier fields below.","type":"boolean","nullable":true},"serviceTypes":{"description":"Default requirement tier. Service types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderTypes":{"description":"Default requirement tier. Provider roles.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"providerTypes":{"description":"Default requirement tier. Provider types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"description":"Default requirement tier. Minimum skill level.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"genderPreferences":{"description":"Default requirement tier. Preferred provider gender.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"certifications":{"description":"Default requirement tier. Required certifications.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"clearances":{"description":"Default requirement tier. Required clearances.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"specializations":{"description":"Default requirement tier. Required specializations.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedClients":{"description":"Clients the consumer may not be scheduled with.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"description":"Consumer users restricted from this consumer.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"assignmentRequest":{"description":"Notification preference.","type":"boolean","nullable":true},"allowClientsToBroadcastImmediately":{"description":"The consumer's requests broadcast without scheduler review.","type":"boolean","nullable":true},"requirementAndPreferences":{"description":"Required with customizeRequirementPreferences=true when publishing a consumer that has no service type yet.","type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Consumer created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer created successfully."},"data":{"properties":{"id":{"type":"string","example":"CSM-000123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The given data was invalid."},"errors":{"properties":{"email":{"type":"array","items":{"type":"string","example":"The email field is required."}}},"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Consumer creation failed: [error details]","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:write","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `consumers:write`  \n**Roles:** admin, scheduler","x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/providers":{"get":{"tags":["Providers"],"summary":"Retrieve a list of service providers","description":"**Required scope:** `providers:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of service providers based on search criteria, filters, and sorting options.","operationId":"ext_get_providers","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter service providers by name, email, or provider ID.","required":false,"schema":{"type":"string","example":"jane"}},{"name":"status","in":"query","description":"Filter service providers by status ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"hearingStatus","in":"query","description":"Filter service providers by hearing status.","required":false,"schema":{"type":"string","enum":["deaf","hard_to_hearing","hearing","deaf_blind"],"example":"deaf"}},{"name":"employmentStatus","in":"query","description":"Filter service providers by employment status.","required":false,"schema":{"type":"string","enum":["full_time","part_time","contractor"],"example":"full_time"}},{"name":"skillLevel","in":"query","description":"Filter service providers by skill ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"serviceType","in":"query","description":"Filter service providers by service type ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"certification","in":"query","description":"Filter service providers by certification ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"clearance","in":"query","description":"Filter service providers by clearance ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"specialization","in":"query","description":"Filter service providers by specialization ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"isPublished","in":"query","description":"Filter service providers by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"sortBy","in":"query","description":"Sort service providers by a specific field (e.g., 'name', 'created_at').","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of service providers to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number to retrieve.","required":false,"schema":{"type":"integer","example":1}},{"name":"columns","in":"query","description":"Search query within visible column content.","required":false,"schema":{"type":"string","example":"user,status,serviceType"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter service providers created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter service providers created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}}],"responses":{"200":{"description":"Service providers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"name":{"type":"string","example":"Example name"},"email":{"type":"string","example":"user@example.com","nullable":true},"phone":{"type":"string","example":"+1-555-0142","nullable":true},"logo":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object","nullable":true},"activeAssignments":{"description":"Count of active assignments and shifts linked to the provider","type":"integer","example":3},"lastAssignmentDate":{"type":"string","example":"2026-01-15","nullable":true},"specializations":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Background Check"}},"type":"object"}},"employmentStatus":{"type":"string","nullable":true},"serviceProviderRole":{"type":"string","nullable":true},"hearingStatus":{"type":"string","nullable":true},"skill":{"type":"string","nullable":true},"certifications":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"NIC"}},"type":"object"}},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL Interpreting"}},"type":"object"}},"serviceProviderTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Interpreter"}},"type":"object"}},"statusChangedAt":{"type":"string","example":"2026-01-15","nullable":true},"publishedAt":{"type":"string","example":"2026-01-15","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"portalAccess":{"type":"boolean","example":true,"nullable":true},"canLogin":{"type":"boolean","example":true},"gender":{"properties":{"id":{"type":"string","example":"male"},"label":{"type":"string","example":"Male"}},"type":"object","nullable":true},"onlineStatus":{"type":"string","example":"online"},"requiresPrimaryReassignmentOnDelete":{"type":"string"},"otherActiveRoles":{"type":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0},"post":{"tags":["Providers"],"summary":"Create a service provider","description":"**Required scope:** `providers:write`  \n**Roles:** admin, scheduler\n\nCreates a provider in this organization. Rates & Billing fields (rates, single rates, admin fee, billing and cancellation terms) need Finance Write: without it they are left out and the new record takes the organization's.","operationId":"ext_post_providers","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID.","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"An organization's service provider, as the create and update forms send it. Sent as multipart/form-data when a logo, document or qualification file is attached; nested objects and lists may then be JSON-encoded strings. Fields marked 'required when published' are required only with isPublished=true.","required":["name","email"],"properties":{"name":{"type":"string","maxLength":255,"example":"Sam Rivera"},"email":{"description":"Unique among this organization's users.","type":"string","format":"email","maxLength":255,"example":"sam@example.test"},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"status":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"serviceProviderRole":{"description":"Required when published. id is individual or agency.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"employmentStatus":{"description":"Required when published.","type":"string","enum":["full_time","part_time","contractor"],"nullable":true},"employmentStartDate":{"description":"Required when published.","type":"string","format":"date","nullable":true},"employmentEndDate":{"description":"On or after employmentStartDate.","type":"string","format":"date","nullable":true},"gender":{"description":"Required when published for an individual provider.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateOfBirth":{"description":"Optional.","type":"string","format":"date","nullable":true},"hearingStatus":{"description":"Required when published for an individual provider.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"portalAccess":{"description":"Let the provider sign in to the provider portal.","type":"boolean","nullable":true},"networkAccess":{"description":"Share the provider with the Fido network.","type":"boolean","nullable":true},"enableCalendarIntegration":{"type":"boolean","nullable":true},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required when published unless videoPhone is sent, and when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"phoneExtension":{"type":"string","maxLength":10,"nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"userPreferred":{"description":"Users this provider prefers.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"description":"Users restricted from this provider.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientRestricted":{"description":"Client users restricted from this provider.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"description":"Consumer users restricted from this provider.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"allowClientsToBroadcastImmediately":{"description":"Requests for this provider broadcast without scheduler review.","type":"boolean","nullable":true},"addressLine1":{"description":"Optional.","type":"string","maxLength":255,"nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"description":"Required when published.","type":"string","maxLength":100,"nullable":true},"state":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"Optional. 12345 or 12345-6789.","type":"string","example":"78759","nullable":true},"assignmentRequest":{"description":"Notification preference.","type":"boolean","nullable":true},"assignmentUpdates":{"description":"Notification preference.","type":"boolean","nullable":true},"serviceReminders":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"profileShareWithinOrganization":{"type":"boolean","nullable":true},"defaultServices":{"description":"Service type and provider type pairs the provider delivers. Each pair must be unique.","type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"isDefault":{"type":"boolean","nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"providerQualifications":{"description":"Certifications held, per service type and provider type.","type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"isDefault":{"type":"boolean","nullable":true},"serviceType":{"description":"One {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"serviceProviderType":{"description":"One {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"certification":{"type":"array","items":{"description":"One certification or clearance a provider holds.","properties":{"id":{"description":"Existing row to keep or update.","type":"integer","nullable":true},"serviceType":{"description":"The certification or clearance itself.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startDate":{"description":"Issue date. Required for a clearance.","type":"string","format":"date","nullable":true},"endDate":{"description":"Expiration date, after startDate. Required when the certification or clearance has expiration tracking on.","type":"string","format":"date","nullable":true},"file":{"description":"Proof document, max 2 MB. Required when the certification or clearance requires an upload.","type":"string","format":"binary","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"clearances":{"description":"One entry per clearance; serviceType holds the clearance.","type":"array","items":{"description":"One certification or clearance a provider holds.","properties":{"id":{"description":"Existing row to keep or update.","type":"integer","nullable":true},"serviceType":{"description":"The certification or clearance itself.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startDate":{"description":"Issue date. Required for a clearance.","type":"string","format":"date","nullable":true},"endDate":{"description":"Expiration date, after startDate. Required when the certification or clearance has expiration tracking on.","type":"string","format":"date","nullable":true},"file":{"description":"Proof document, max 2 MB. Required when the certification or clearance requires an upload.","type":"string","format":"binary","nullable":true}},"type":"object"},"nullable":true},"certifications":{"description":"Legacy flat list; serviceType holds the certification. The form sends providerQualifications instead.","type":"array","items":{"description":"One certification or clearance a provider holds.","properties":{"id":{"description":"Existing row to keep or update.","type":"integer","nullable":true},"serviceType":{"description":"The certification or clearance itself.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startDate":{"description":"Issue date. Required for a clearance.","type":"string","format":"date","nullable":true},"endDate":{"description":"Expiration date, after startDate. Required when the certification or clearance has expiration tracking on.","type":"string","format":"date","nullable":true},"file":{"description":"Proof document, max 2 MB. Required when the certification or clearance requires an upload.","type":"string","format":"binary","nullable":true}},"type":"object"},"nullable":true},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"availability":{"description":"Weekly office availability.","type":"array","items":{"properties":{"day":{"type":"string","example":"monday"},"isAvailable":{"type":"boolean","example":true},"slots":{"type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"17:00:00"}},"type":"object"}}},"type":"object"},"nullable":true},"vacations":{"description":"Time off. A vacation left out of an update is removed.","type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"reason":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date","example":"2025-07-01"},"endDate":{"type":"string","format":"date","example":"2025-07-04"},"startTime":{"type":"string","example":"00:00:00"},"endTime":{"type":"string","example":"23:59:00"}},"type":"object"},"nullable":true},"scheduleType":{"description":"Shape of dateTimeSlots.","type":"string","enum":["one_time","recurring","multi_day"],"nullable":true},"dateTimeSlots":{"type":"array","items":{"properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"17:00:00"}},"type":"object"},"nullable":true}},"type":"object"},"nullable":true},"maxAssignmentsPerWeek":{"type":"integer","nullable":true},"maxAssignmentsPerDay":{"type":"integer","nullable":true},"bufferBeforeMinutes":{"type":"integer","maximum":240,"minimum":0,"nullable":true},"bufferAfterMinutes":{"type":"integer","maximum":240,"minimum":0,"nullable":true},"travelRadius":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"preferredServiceLocations":{"description":"Required when published. id is onsite, remote or both.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timezone":{"type":"string","example":"America/Chicago","nullable":true},"defaultTimezone":{"description":"Localization. Required when published.","type":"string","example":"America/Chicago","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization. Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization. Required when published.","type":"string","nullable":true},"startOfWeek":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startOfDay":{"description":"Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"Localization.","type":"string","example":"18:00","nullable":true},"restrictedClients":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedConsumers":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedServiceProviders":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"preferredClients":{"description":"Must not overlap restrictedClients.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"preferredConsumers":{"description":"Must not overlap restrictedConsumers.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"preferredServiceProviders":{"description":"Must not overlap restrictedServiceProviders.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"enableCustomRates":{"description":"Use the provider's own rates. Makes rates required.","type":"boolean","nullable":true},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"},"nullable":true},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"},"nullable":true},"adminFee":{"type":"number","nullable":true},"adminFeeType":{"type":"string","enum":["assignment","shift","both"],"nullable":true},"providerAdminFeeMethod":{"type":"string","enum":["flat","percentage"],"nullable":true},"internalNotes":{"type":"string","nullable":true},"documents":{"description":"pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each.","type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Service provider created","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service provider created successfully."},"data":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation failures use their own envelope — status rather than success, and no code.","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages. Nested keys are collapsed onto the field the form renders.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:write","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/check-ins":{"get":{"tags":["Check Ins"],"summary":"List provider sign-ins and sign-outs for a date range","description":"**Required scope:** `check_ins:read`\n\nOne row per assigned provider slot on every assignment and shift whose dates reach into the range (from to to, inclusive, by the work item's own dates), with that provider's sign-in and sign-out on the work item when one is recorded. A provider who holds two slots on one work item appears twice, with the same sign-in and sign-out on both rows; a provider with no check-in yet appears with signIn, signOut, status and duration empty. Dates and times are wall-clock values in the work item's time zone (timeZone); each moment also carries its UTC offset in `at`. Rows are sorted by date, then work item, provider and slot. An admin sees everything; a scheduler sees the kinds its Assignments and Shifts access allows; a service provider sees only their own rows. Requests, deleted work items and providers who are not assigned are not listed. Names and signature images are not part of the response.","operationId":"ext_get_check_ins","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"from","in":"query","description":"First day to include (YYYY-MM-DD). Required unless updated_since is sent, and then with to.","required":false,"schema":{"type":"string","format":"date","example":"2026-10-01"}},{"name":"to","in":"query","description":"Last day to include (YYYY-MM-DD). Required unless updated_since is sent, and then with from. Not before from.","required":false,"schema":{"type":"string","format":"date","example":"2026-10-31"}},{"name":"userId","in":"query","description":"Only this provider's rows.","required":false,"schema":{"type":"string","example":"SPR-4EVTY9"}},{"name":"workId","in":"query","description":"Only this assignment's or shift's rows. An id starting ASG- is an assignment, one starting SFT- a shift.","required":false,"schema":{"type":"string","example":"ASG-VQM5KW"}},{"name":"status","in":"query","description":"Only rows whose check-in has this status. Rows with no check-in are left out.","required":false,"schema":{"type":"string","enum":["pending","approved","rejected"],"example":"approved"}},{"name":"updated_since","in":"query","description":"Only rows that changed at or after this moment: the provider's check-in, the provider row (assigned, or removed: providerStatus canceled, withdrawn, un_assigned or declined), the slot, or the work item itself. Work items deleted in the window come back with deletedAt set. With it, from and to become optional. ISO 8601 date-time with a time zone (for example 2026-10-22T06:00:00Z) or a date (YYYY-MM-DD, taken as 00:00 UTC). meta.asOf is the moment the list was read; use it as the next updated_since. Keep the meta.asOf of the first page of a pull: every page reports its own, and the first one is the moment the pull began. Start each pull a few minutes before the previous meta.asOf: a change committed while a list was being read can carry a time just before it, and a row returned twice is harmless.","required":false,"schema":{"type":"string","example":"2026-10-22T06:00:00Z"}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"perPage","in":"query","description":"Rows per page (default: 25, at most 100).","required":false,"schema":{"type":"integer","example":25}}],"responses":{"200":{"description":"Check-ins retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Check-ins retrieved successfully."},"data":{"type":"array","items":{"properties":{"workItemType":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"assignmentId":{"type":"string","example":"ASG-VQM5KW","nullable":true},"shiftId":{"type":"string","example":null,"nullable":true},"userId":{"description":"The provider.","type":"string","example":"SPR-4EVTY9"},"slotId":{"description":"The provider's assigned slot; empty when the provider is not tied to a slot.","type":"string","example":"214","nullable":true},"timeZone":{"description":"The work item's time zone. Every date and time on the row is a wall-clock value in it.","type":"string","example":"America/New_York"},"scheduledStart":{"description":"The slot's own start, else the work item's.","properties":{"date":{"type":"string","format":"date","example":"2026-10-01"},"time":{"type":"string","example":"13:00:00"},"at":{"type":"string","format":"date-time","example":"2026-10-01T13:00:00-04:00"}},"type":"object","nullable":true},"scheduledEnd":{"description":"The slot's own end, else the work item's; the next day for work that runs past midnight.","properties":{"date":{"type":"string","format":"date","example":"2026-10-01"},"time":{"type":"string","example":"15:30:00"},"at":{"type":"string","format":"date-time","example":"2026-10-01T15:30:00-04:00"}},"type":"object","nullable":true},"signIn":{"description":"Empty until the provider signs in.","properties":{"date":{"type":"string","format":"date","example":"2026-10-01"},"time":{"type":"string","example":"13:15:00"},"at":{"type":"string","format":"date-time","example":"2026-10-01T13:15:00-04:00"}},"type":"object","nullable":true},"signOut":{"description":"Empty until the provider signs out.","properties":{"date":{"type":"string","format":"date","example":"2026-10-01"},"time":{"type":"string","example":"15:30:00"},"at":{"type":"string","format":"date-time","example":"2026-10-01T15:30:00-04:00"}},"type":"object","nullable":true},"status":{"description":"The check-in's review status; empty when there is no check-in.","type":"string","enum":["pending","approved","rejected"],"example":"approved","nullable":true},"duration":{"description":"Hours between sign-in and sign-out; empty until both are recorded.","type":"number","format":"float","example":2.25,"nullable":true},"providerStatus":{"description":"Only with updated_since: the provider row's status. Anything but assigned means the provider left the job.","type":"string","enum":["assigned","canceled","withdrawn","un_assigned","declined"],"example":"assigned"},"providerRowId":{"description":"Only with updated_since: the id of the provider row. A provider can have a canceled row and an assigned row on the same slot; this tells them apart. Unique only together with workItemType: assignment and shift provider rows count their ids separately.","type":"integer","example":661},"providerRowUpdatedAt":{"description":"Only with updated_since: when the provider row last changed (UTC, ending in Z).","type":"string","format":"date-time","example":"2026-10-23T06:00:00Z"},"deletedAt":{"description":"Only with updated_since: when the work item was deleted (UTC, ending in Z), or empty while it exists.","type":"string","format":"date-time","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":25},"total":{"type":"integer","example":61},"asOf":{"description":"Only with updated_since: the moment the list was read; use it as the next updated_since. Take it from the first page of a pull; every page reports its own.","type":"string","format":"date-time","example":"2026-10-23T06:00:00Z"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The caller is not an admin, a scheduler with Read on Assignments or Shifts (and on the kind of the work id), or a service provider asking for their own rows.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'check_ins:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"A date is missing or malformed, to is before from, or workId does not start with ASG- or SFT-.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"type":"object","example":{"to":["The to date cannot be before the from date."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"check_ins:read","x-fido-module":"check_ins","x-fido-roles":[],"x-fido-area":"Check-ins","x-fido-area-rank":0}},"/v1/assignment-clients/{id}/no-show":{"delete":{"tags":["Assignments"],"summary":"Reverse a client No Show mark","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler\n\nClears the No Show flag for a client on an assignment — the correction path when the mark was applied by mistake. Restores the client to the served count and to normal billing treatment, and clears any no-show fee entered with the mark.","operationId":"ext_delete_assignment_clients_By_id_no_show","parameters":[{"name":"id","in":"path","description":"assignment_client row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"reason":{"type":"string","maxLength":1000,"example":"Marked in error — client did attend","nullable":true},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"No Show reversed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"No Show has been removed for this client."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Client is not currently marked as No Show","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":2},"post":{"tags":["Assignments"],"summary":"Mark a client as No Show on an assignment","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler\n\nRecords that a client attached to this assignment did not show, without changing the assignment status or detaching the client — the booking record stays intact. The client is moved out of the served count and billed the no-show fee instead of the delivered service. An optional per-client fee can be entered with the mark; client no-show money has no policy fallback, so an omitted fee simply bills nothing.","operationId":"ext_post_assignment_clients_By_id_no_show","parameters":[{"name":"id","in":"path","description":"assignment_client row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["reason"],"properties":{"reason":{"type":"string","maxLength":1000,"example":"Client did not attend the appointment"},"noShowFee":{"type":"number","format":"float","example":75,"nullable":true},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Client marked as No Show","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client has been marked as No Show."},"data":{"properties":{"id":{"type":"string","example":"ASG-ZGJ8T2"},"clientId":{"type":"string","example":"CLT-4HD92K"},"isNoShow":{"type":"boolean","example":true},"noShowReason":{"type":"string","example":"Client did not attend the appointment"},"noShowFee":{"type":"number","format":"float","example":75},"affectedRows":{"type":"integer","example":1},"summary":{"properties":{"attached":{"type":"integer","example":3},"noShow":{"type":"integer","example":1},"served":{"type":"integer","example":2}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error — missing reason, unknown client record, or client already marked","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":2}},"/v1/assignment-default-options":{"get":{"tags":["Assignments"],"summary":"Retrieve default options for assignment shift dropdowns","description":"**Required scope:** `assignments:read` or `shifts:read`\n\nFetch default timezone, priority, and requireVerifiedTimeDocumentation based on context (client, consumer, location, or organization defaults)","operationId":"ext_get_assignment_default_options","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":false,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"clientId","in":"query","description":"Client ID to fetch defaults for","required":false,"schema":{"type":"string","example":"CLT-UXVM8P"}},{"name":"consumerId","in":"query","description":"Consumer ID to fetch defaults for","required":false,"schema":{"type":"string","example":"CNS-ABC123"}},{"name":"clientLocationId","in":"query","description":"Client Location ID to fetch defaults for","required":false,"schema":{"type":"string","example":"CLTLOC-RPYA1"}},{"name":"organizationLocationId","in":"query","description":"Organization Location ID to fetch defaults for","required":false,"schema":{"type":"string","example":"ORGLOC-9XYZ7"}}],"responses":{"200":{"description":"Default options retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment shift dropdown options retrieved."},"data":{"properties":{"timezone":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"America/New_York"}},"type":"object"},"priority":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"High"}},"type":"object"},"requireVerifiedTimeDocumentation":{"type":"boolean","example":false}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Assignment shift dropdown options retrieved.","data":{"timezone":{"id":1,"value":1,"label":"America/New_York"},"priority":{"id":2,"label":"High"},"requireVerifiedTimeDocumentation":false}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred — please try again."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read|shifts:read","x-fido-module":"assignments","x-fido-roles":[],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignment-export/{id}":{"get":{"tags":["Assignments"],"summary":"Export Single or Multiple Assignments to Excel","description":"**Required scope:** `assignments:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports one or more assignments into an Excel file. For multiple IDs, provide a comma-separated list (e.g., ASG-123,ADJO-131,AJD-2313).","operationId":"ext_get_assignment_export_By_id","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"path","description":"Assignment ID(s) to export. Can be a single ID or multiple comma-separated IDs.","required":true,"schema":{"type":"string"},"examples":{"single":{"summary":"Single assignment","value":"ASG-45FDX"},"multiple":{"summary":"Multiple assignments","value":"ASG-123142,ADJO-131,AJD-2313"}}}],"responses":{"200":{"description":"Excel file containing the requested assignment(s)","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad request – invalid or missing assignment IDs","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"No valid IDs provided."}},"type":"object"}}}},"401":{"description":"Unauthorized – authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not found – no assignments matched the provided IDs","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"No assignments found with the provided IDs."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Export","x-fido-area-rank":5}},"/v1/assignment-providers/{id}":{"patch":{"tags":["Assignments"],"summary":"Update provider status for an assignment","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler\n\nUpdates the status of a provider for a specific assignment.","operationId":"ext_patch_assignment_providers_By_id","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["status"],"properties":{"status":{"description":"'message' sends a message to the provider instead of changing their status — see subject/message below.","type":"string","enum":["assigned","rebroadcast","resend_details","message","declined","interested","not_interested","canceled","pending","un_assigned"],"example":"assigned"},"subject":{"description":"Required when status is 'message'.","type":"string","maxLength":255,"example":"Update on your assignment"},"message":{"description":"Required when status is 'message'.","type":"string","maxLength":5000,"example":"Please confirm your availability."},"reason":{"type":"string","maxLength":1000,"example":"Provider requested time off","nullable":true},"notes":{"type":"string","maxLength":1000,"example":"Internal note for the scheduler","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Provider status updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider status updated successfully"},"data":{"properties":{"id":{"type":"string","example":"ASM-ZGJ8T2"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"type":"object","example":{"providerId":["The selected provider does not exist."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":2}},"/v1/assignment-providers/{id}/no-show":{"delete":{"tags":["Assignments"],"summary":"Reverse a provider No Show mark","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler\n\nClears the No Show flag for a provider on an assignment — the correction path when the mark was applied by mistake. Restores the provider to the delivered coverage count and to normal billing treatment. Applies to every booked line the provider holds on this assignment.","operationId":"ext_delete_assignment_providers_By_id_no_show","parameters":[{"name":"id","in":"path","description":"assignment_providers row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"reason":{"type":"string","maxLength":1000,"example":"Marked in error — provider did attend","nullable":true},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"No Show reversed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"No Show has been removed for this provider."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Provider is not currently marked as No Show, or FINANCIAL_CONSENT_REQUIRED when billed docs need affectFinancials","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":2},"post":{"tags":["Assignments"],"summary":"Mark an assigned provider as No Show","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler\n\nFlags a single provider on an assignment as No Show without changing the assignment status and without reopening the slot. The provider stays assigned — the booking record is history — so coverage continues to report them under `assigned` with the no-show count alongside. Applies to every booked line the provider holds on this assignment. `{id}` is an assignment_providers row id; the provider it points at is marked in full.","operationId":"ext_post_assignment_providers_By_id_no_show","parameters":[{"name":"id","in":"path","description":"assignment_providers row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["reason"],"properties":{"reason":{"type":"string","maxLength":1000,"example":"Did not arrive on site"},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Provider marked as No Show","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider has been marked as No Show."},"data":{"properties":{"id":{"type":"string","example":"ASG-ZGJ8T2"},"serviceProviderId":{"type":"string","example":"SPR-4HD92K"},"isNoShow":{"type":"boolean","example":true},"noShowReason":{"type":"string","example":"Did not arrive on site"},"affectedRows":{"type":"integer","example":2},"summary":{"properties":{"required":{"type":"integer","example":3},"assigned":{"type":"integer","example":3},"noShow":{"type":"integer","example":1},"delivered":{"type":"integer","example":2}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error, unknown provider record, or FINANCIAL_CONSENT_REQUIRED when billed docs need affectFinancials","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":2}},"/v1/assignment-shift/provider/check-in":{"get":{"tags":["Check Ins"],"summary":"Get one provider's sign-in / sign-out record on an assignment or a shift","description":"**Required scope:** `check_ins:read`\n\nAdmin may read any provider's record; a scheduler may too when their module permissions give them Read on Assignments (assignmentId) or Shifts (shiftId). A service provider may read only their own (userId is their own id) on a work item they are assigned to. Every other role gets 403. Send assignmentId or shiftId, not both. data is an empty record (all keys null) when nothing has been recorded yet; signInSignOutRequired is always set.","operationId":"ext_get_assignment_shift_provider_check_in","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"assignmentId","in":"query","description":"Required without shiftId; not with shiftId","required":false,"schema":{"type":"string","example":"ASG-VQM5KW"}},{"name":"shiftId","in":"query","description":"Required without assignmentId; not with assignmentId","required":false,"schema":{"type":"string","example":"SFT-1A2B3C"}},{"name":"userId","in":"query","description":"The provider whose record is read","required":true,"schema":{"type":"string","example":"SPR-4EVTY9"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Get Provider Check Ins."},"data":{"properties":{"id":{"type":"integer","example":12,"nullable":true},"assignmentId":{"type":"string","example":"ASG-VQM5KW","nullable":true},"shiftId":{"type":"string","example":null,"nullable":true},"signInDate":{"type":"string","format":"date","example":"2026-10-01","nullable":true},"signInTime":{"type":"string","example":"13:15:00","nullable":true},"signOutDate":{"type":"string","format":"date","example":"2026-10-01","nullable":true},"signOutTime":{"type":"string","example":"15:30:00","nullable":true},"status":{"type":"string","enum":["pending","approved","rejected"],"example":"pending","nullable":true},"timesLocked":{"description":"True when a service provider can no longer change or clear the times: an admin or scheduler has written the record, or it is approved. False for a rejected record, which the provider can resubmit (it goes to pending)","type":"boolean","example":false},"signInSignOutRequired":{"description":"The work item's require_verified_time_documentation (Require verified time records): when true the times are required and cannot be cleared","type":"boolean","example":true},"scheduledSignIn":{"description":"Where the sign-in opens when nothing is saved: the scheduled start (the provider's own assigned slot for partial coverage), in the work item's time zone","properties":{"date":{"type":"string","example":"2026-10-01"},"time":{"type":"string","example":"09:00:00"}},"type":"object","nullable":true},"scheduledSignOut":{"description":"Where the sign-out opens when nothing is saved: the scheduled end (the next day for work past midnight)","properties":{"date":{"type":"string","example":"2026-10-01"},"time":{"type":"string","example":"17:00:00"}},"type":"object","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Not admin, not a scheduler with Read on the work item's module, and not the assigned provider reading their own record","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'check_ins:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error: missing or unknown work item or provider, or both assignmentId and shiftId sent","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"type":"object","example":{"userId":["The provider is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"check_ins:read","x-fido-module":"check_ins","x-fido-roles":[],"x-fido-area":"Check-ins","x-fido-area-rank":0}},"/v1/assignment-statuses":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve paginated assignment statuses with optional filters","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of assignment statuses. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_assignment_statuses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"completed"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"Name","in":"query","description":"Search by name or ID","required":false,"schema":{"type":"string","example":"Completed"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Assignment statuses retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Completed"},"description":{"type":"string","example":"Includes both successfully finished and No Show assignments."},"parentId":{"type":"integer","example":1},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment statuses","x-fido-area-rank":4},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new assignment status","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new assignment statuse with a name,description and parent.","operationId":"ext_post_assignment_statuses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"New Assignment Status"},"description":{"type":"string","example":"This is test description for new assignment status.","nullable":true},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Assignment status created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment status created!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"New assignment status"},"description":{"type":"string","example":"This is test description for new assignment status."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Assignment status created!","data":{"id":10,"name":"New assignment status","description":"This is test description for new assignment status.","parent":{"id":1,"label":"Pending"},"isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment statuses","x-fido-area-rank":4}},"/v1/assignment-statuses/{assignment_status}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete an assignment status","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete an assignment status by its ID.","operationId":"ext_delete_assignment_statuses_By_assignment_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"assignment_status","in":"path","description":"ID of the assignment status to delete.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Assignment status deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment status deleted!"}},"type":"object"},"example":{"success":true,"message":"Assignment status deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Assignment status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment statuses","x-fido-area-rank":4},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve an assignment status by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch an assignment status by its ID.","operationId":"ext_get_assignment_statuses_By_assignment_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"assignment_status","in":"path","description":"ID of assignment status to retrieve.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Assignment status retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment status retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"description":{"type":"string","example":"Short human-readable description."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Assignment status retrieved successfully!","data":{"id":1,"name":"Example name","description":"Short human-readable description.","parent":{"id":1,"label":"Example label"},"isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Assignment status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment statuses","x-fido-area-rank":4},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing assignment status","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing assignment status by ID.","operationId":"ext_put_assignment_statuses_By_assignment_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"assignment_status","in":"path","description":"ID of the assignment status to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated assignment status"},"description":{"type":"string","example":"This is test description for updated assignment status.","nullable":true},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Assignment status updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment status updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"Updated assignment status"},"description":{"type":"string","example":"This is test description for updated assignment status."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Assignment status updated!","data":{"id":10,"name":"Updated assignment status","description":"This is test description for updated assignment status.","parent":{"id":1,"label":"Pending"},"isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Assignment status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment statuses","x-fido-area-rank":4},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing assignment status","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing assignment status by ID.","operationId":"ext_patch_assignment_statuses_By_assignment_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"assignment_status","in":"path","description":"ID of the assignment status to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated assignment status"},"description":{"type":"string","example":"This is test description for updated assignment status.","nullable":true},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Assignment status updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment status updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"Updated assignment status"},"description":{"type":"string","example":"This is test description for updated assignment status."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Assignment status updated!","data":{"id":10,"name":"Updated assignment status","description":"This is test description for updated assignment status.","parent":{"id":1,"label":"Pending"},"isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Assignment status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment statuses","x-fido-area-rank":4}},"/v1/assignment-summary/{id}/{tab}":{"get":{"tags":["Assignments"],"summary":"Get Assignment Summary Tab Details","description":"**Required scope:** `assignments:read`  \n**Roles:** admin, scheduler\n\nRetrieve assignment details for a specific tab (summary, historyLogs, insights) for the given tenant. Without Finance Read the money figures are null: the parent summary's `totalRevenue`, each assigned provider's `estimatedPay` and the insights' `estimatedCost.total`; each provider's `rates` is empty.","operationId":"ext_get_assignment_summary_By_id_By_tab","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"Assignment ID","required":true,"schema":{"type":"string","example":"ASG-12345"}},{"name":"tab","in":"path","description":"Tab name for which assignment details are requested","required":true,"schema":{"type":"string","enum":["summary","historyLogs","insights"],"example":"summary"}},{"name":"search","in":"query","description":"Search the audit log. Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort column (default: created_at). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort direction (default: desc). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Rows per page (default: 10). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number (default: 1). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Assignment details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment details retrieved successfully."},"data":{"description":"Assignment details depend on the selected tab","type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignment/cancel-assignment":{"post":{"tags":["Assignments"],"summary":"Request cancellation of an assignment or shift (client and consumer)","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, client, scheduler, consumer\n\nRecords a client's or consumer's request to cancel an assignment or shift and notifies the currently assigned provider and the organization's admins/schedulers — it does not cancel the assignment/shift itself or calculate a fee. The organization cancels it by updating the record's status instead (POST /v1/assignments/{id} or POST /v1/shifts/{id} with the Canceled status and cancellationDetails), which is why a staff (admin, scheduler) caller receives 409 here rather than a misleading 200. Submitting again for the same assignment/shift updates the stored reason and increments a running request count rather than creating a duplicate.","operationId":"ext_post_assignment_cancel_assignment","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["id","reasonForCancellation"],"properties":{"id":{"description":"ID of the assignment or shift (ASG-prefixed for an assignment, otherwise a shift) to request cancellation for","type":"string","example":"ASG-J5A17Q-C1"},"reasonForCancellation":{"description":"Reason for requesting the cancellation; sent to the organization and the assigned provider","type":"string","example":"I have another appointment at the same time"},"startTime":{"description":"Optional; not read by the server","type":"string","example":"06:16 AM"},"startDate":{"description":"Optional; not read by the server","type":"string","example":"17/10/2025"}},"type":"object"}}}},"responses":{"200":{"description":"Cancellation request recorded and the organization notified; the assignment/shift itself is unchanged until the organization cancels it","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Cancel assignment request submitted successfully"}},"type":"object"}}}},"400":{"description":"Request rejected — the assignment/shift is not in a cancelable state (already completed, already canceled, not yet filled, or its end date/time has passed), or its appointment has already started or ended.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment has already been canceled."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden — a client or consumer who is not attached to this assignment/shift. The message is generic on purpose, so the response can't be used to tell a real id apart from one belonging to someone else.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"409":{"description":"Staff caller: the request to cancel is not recorded; cancel by updating the record status","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"This endpoint records a client or consumer request to cancel and does not cancel the assignment. To cancel it as staff, update the record's status to Canceled with cancellationDetails (POST /v1/assignments/{id} for an assignment, POST /v1/shifts/{id} for a shift)."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"reasonForCancellation":["The reason for cancellation field is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to cancel assignment"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","client","scheduler","consumer"],"x-fido-area":"Cancel, change and reassign","x-fido-area-rank":3}},"/v1/assignment/document/files":{"delete":{"tags":["Assignments"],"summary":"Delete assignment files by file IDs","operationId":"ext_delete_assignment_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileIds":{"description":"File IDs to delete. Missing, empty, or not an array is treated as no IDs given — see the 200 response.","type":"array","items":{"type":"integer"},"example":[101,102]}},"type":"object"}}}},"responses":{"200":{"description":"Request processed — never rejected for missing/empty/malformed fileIds. A fileId that doesn't resolve to a real document is skipped rather than failing the request; if none of the given IDs resolved (including when fileIds was missing or empty), the message reports that nothing was deleted instead of a file count.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"All files were deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Assignment files deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler","x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignment/export":{"get":{"tags":["Assignments"],"summary":"Export All Assignments to Excel","description":"**Required scope:** `assignments:read`  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all assignments to an Excel file for download.","operationId":"ext_get_assignment_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"query","description":"Optional assignment ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing assignments","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":[],"x-fido-rate-limit":"heavy","x-fido-area":"Export","x-fido-area-rank":5}},"/v1/assignment/re-assign":{"post":{"tags":["Assignments"],"summary":"Reassign an assignment","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler\n\nReassigns an assignment to a new service provider with optional priority and reason.","operationId":"ext_post_assignment_re_assign","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["assignmentId"],"properties":{"assignmentId":{"type":"string","example":"ASG-LVMXVD"},"newAssignee":{"required":["id"],"properties":{"id":{"type":"string","example":"SPR-JVI5GD"},"label":{"type":"string","example":"Demo User"}},"type":"object"},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"HIGH"}},"type":"object"},"reassignmentReason":{"type":"string","example":"Demo reason","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Assignment reassigned successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment reassigned successfully."},"data":{"type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"Validation failed."},"errors":{"type":"object","example":{"assignmentId":["The selected assignment does not exist."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"Assignment reassignment failed."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"An unexpected error occurred — please try again.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"Cancel, change and reassign","x-fido-area-rank":3}},"/v1/assignment/request-change-assignment":{"post":{"tags":["Assignments"],"summary":"Submit a change request for an assignment or shift","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, client, scheduler, consumer\n\nRecords a request to change an assignment or shift (e.g., time, provider, location) and notifies the organization — it does not change the assignment/shift itself. Typically called by the client or consumer attached to it to tell the assignment manager what they'd like changed (admin and scheduler may also call this directly, e.g. on a client's behalf). On success this emails the currently assigned provider with the requested change and reason, and notifies the organization's admins/schedulers so one of them can action the actual change.","operationId":"ext_post_assignment_request_change_assignment","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["id","changeType","reason"],"properties":{"id":{"description":"ID of the assignment or shift (ASG-prefixed for an assignment, otherwise a shift) to request a change for","type":"string","example":"ASG-J5A17Q-C1"},"changeType":{"description":"Type of change requested (e.g., Time, Provider, Location)","type":"string","example":"Time"},"reason":{"description":"Reason for requesting the change; sent to the organization and the assigned provider","type":"string","example":"That time, I have lots of work"},"additionalDetails":{"description":"Any extra information about the request","type":"string","example":"Testing","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Change request recorded and the organization notified","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request change notification sent successfully"}},"type":"object"}}}},"400":{"description":"Request rejected — the assignment/shift is not in a state that can be changed (already completed, already canceled, not yet filled, or its end date has passed).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment end date has passed."}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden — a client or consumer who is not attached to this assignment/shift. The message is generic on purpose, so the response can't be used to tell a real id apart from one belonging to someone else.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"reason":["The reason field is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error. Also returned for an id that does not match an assignment or shift; this endpoint does not return 404.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","client","scheduler","consumer"],"x-fido-area":"Cancel, change and reassign","x-fido-area-rank":3}},"/v1/assignment/send-message":{"post":{"tags":["Assignments"],"summary":"Send a message related to an assignment","description":"**Required scope:** `assignments:write`\n\nAllows user to send messages or notifications related to a specific assignment to multiple recipient types (scheduler, client, consumer).","operationId":"ext_post_assignment_send_message","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["assignmentId","message","subject"],"properties":{"scheduler":{"description":"Whether to send the message to the scheduler","type":"boolean","example":true,"nullable":true},"client":{"description":"Whether to send the message to the client","type":"boolean","example":true},"consumer":{"description":"Whether to send the message to the consumer","type":"boolean","example":true},"subject":{"description":"Subject of the message","type":"string","example":"Send message for testing"},"message":{"description":"Body of the message","type":"string","example":"Lorem ipsum dolor sit amet consectetur adipisicing elit."},"assignmentId":{"description":"Unique ID of the assignment","type":"string","example":"ASG-J5A17Q-C1"},"type":{"description":"Indicates the type of user who is sending the message (e.g., scheduler, client, consumer)","type":"string","example":"consumer"}},"type":"object"}}}},"responses":{"200":{"description":"Message sent successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Message sent successfully"}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden — a client, consumer or service provider who is not attached to this assignment/shift. The message is generic on purpose, so the response can't be used to tell a real id apart from one belonging to someone else.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"message":["The message field is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to send message"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:write","x-fido-module":"assignments","x-fido-roles":[],"x-fido-area":"Cancel, change and reassign","x-fido-area-rank":3}},"/v1/assignment/{id}/providers/{serviceType}/{status}":{"get":{"tags":["Assignments"],"summary":"Retrieve assignment providers","description":"**Required scope:** `assignments:read`  \n**Roles:** admin, scheduler\n\nFetches the assignment providers.","operationId":"ext_get_assignment_By_id_providers_By_serviceType_By_status","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"search","in":"query","description":"Search query to filter provider by name, method","required":false,"schema":{"type":"string","example":"John Doe"}},{"name":"serviceType","in":"path","description":"Identifier for the service type","required":true,"schema":{"type":"integer","example":1}},{"name":"status","in":"path","description":"Status of the assignment providers","required":true,"schema":{"type":"string","enum":["assigned","interested","pending","declined","not_interested","pending_confirmation","un_assigned","broadcasted"],"example":"assigned"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"locationType","in":"query","description":"Limit to providers on this location type.","required":false,"schema":{"type":"string","enum":["onsite","remote"],"example":"onsite"}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Assignment providers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"method":{"type":"string","example":"string"},"status":{"type":"string","example":"string"},"serviceProviderId":{"type":"string","example":"SPR-FG543C"},"onlineStatus":{"type":"string","example":"online"},"name":{"type":"string","example":"Example name"},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"email":{"type":"string","example":"user@example.com"},"distance":{"type":"integer","example":0},"slotType":{"type":"string","example":"string"},"slotStartTime":{"type":"string","format":"time","example":"09:00:00"},"slotEndTime":{"type":"string","format":"time","example":"09:00:00"},"serviceType":{"type":"string","example":"string"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"startDate":{"type":"string","format":"date","example":"2026-01-15"},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endDate":{"type":"string","format":"date","example":"2026-01-15"},"endTime":{"type":"string","format":"time","example":"09:00:00"},"locationType":{"type":"string","example":"string"},"timezone":{"type":"string","example":"America/New_York"},"verifiedTimeLogs":{"type":"boolean","example":true},"isNetwork":{"type":"boolean","example":true},"isNoShow":{"type":"boolean","example":true},"noShowReason":{"type":"string","example":"Client requested a change"},"noShowMarkedAt":{"type":"string","format":"date-time","example":"2026-01-15 09:00:00"},"noShowMarkedBy":{"type":"string","example":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":1},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"method":"string","status":"string","serviceProviderId":"SPR-FG543C","onlineStatus":"online","name":"Example name","image":"https://cdn.example.com/image.png","email":"user@example.com","distance":0,"slotType":"string","slotStartTime":"09:00:00","slotEndTime":"09:00:00","serviceType":"string","serviceProviderType":{"id":1,"label":"Example label"},"startDate":"2026-01-15","startTime":"09:00:00","endDate":"2026-01-15","endTime":"09:00:00","locationType":"string","timezone":"America/New_York","verifiedTimeLogs":true,"isNetwork":true,"isNoShow":true,"noShowReason":"Client requested a change","noShowMarkedAt":"2026-01-15 09:00:00","noShowMarkedBy":"string"}],"meta":{"currentPage":1,"lastPage":1,"perPage":1,"total":1}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified assignment does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified assignment does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignment/{id}/{tab}":{"get":{"tags":["Assignments"],"summary":"Retrieve specific tab details of a assignment","description":"**Required scope:** `assignments:read`\n\nFetches the details for a specific tab within a assignment, based on the provided assignment ID and tab identifier.","operationId":"ext_get_assignment_By_id_By_tab","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details','providers','requirementPreferences','documents','sidebar','providerStats')","required":true,"schema":{"type":"string","enum":["details","providers","requirementPreferences","documents","sidebar"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Assignment details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"string","example":"ASM-MARH4E"},"title":{"type":"string","example":"Assignment Title"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":"ASM-MARH4E","title":"Assignment Title"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified assignment does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified assignment does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":[],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignments/{assignment}":{"delete":{"tags":["Assignments"],"summary":"Delete an assignment","description":"**Required scope:** `assignments:delete`  \n**Roles:** admin, scheduler\n\nDeletes an assignment by ID for the given tenant, including child assignments and associated files from S3.","operationId":"ext_delete_assignments_By_assignment","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"assignment","in":"path","description":"ID of the assignment to delete","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Assignment deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:delete","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignments/{id}":{"post":{"tags":["Assignments"],"summary":"Update an existing assignment","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, scheduler\n\nCarries several distinct actions as payload variations rather than separate\n    endpoints, which is what a tool catalog needs to know to map them:\n    • **Reschedule** — send `dateTimeSlots` (with `scheduleType`, and `scheduleFrequency` when\n      recurring). There is no separate reschedule endpoint; changing the slots *is* the reschedule.\n    • **Broadcast vs direct assignment** — `assignmentMethod`: `direct` assigns the named providers,\n      `broadcast` offers the assignment to the eligible pool. Use `broadcastAudience` to narrow that pool.\n    • **Cancel** — NOT done here. Use POST /assignment/cancel-assignment, which requires\n      `reasonForCancellation` alongside the id and start date/time.\n    There is no start/stop-broadcast action on this endpoint or any other: broadcast state\n    (`off` / `active` / `onhold`) advances through the assignment lifecycle and the scheduled\n    timeout and escalation commands, not through a direct call.","operationId":"ext_post_assignments_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the assignment to be updated","required":true,"schema":{"type":"string","example":"ASG-SA2IVL"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"A partial update: every field is optional and only what is sent is changed — omitted fields keep their stored value. isPublished=true additionally requires whichever of requestorName, timezone, assignTo, scheduleType, location, status and the other publish-required fields the assignment does not already have.","properties":{"title":{"type":"string","example":"Special interpreter — intake appointment","nullable":true},"description":{"type":"string","example":"description of the assignment","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"duration":{"description":"Hours — used when setting location.onsite/remote slot capacity.","type":"number","example":1.5,"nullable":true},"allowPointOfContact":{"type":"string","enum":["client_poc","external_contact","consumer","organization_poc"],"example":"client_poc","nullable":true},"requestorName":{"type":"string","example":"John Doe","nullable":true},"requestorEmail":{"type":"string","format":"email","example":"user@example.com","nullable":true},"requestorPhone":{"type":"string","example":"1234567890","nullable":true},"requestorCountryCode":{"type":"string","example":"+1","nullable":true},"requestorPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"requestorPhoneExtension":{"type":"string","example":"123","nullable":true},"requestorConsumer":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"}},"type":"object","nullable":true},"assignTo":{"type":"string","enum":["client","organization"],"example":"client","nullable":true},"billTo":{"type":"string","enum":["organization","clients"],"example":"clients","nullable":true},"client":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object","nullable":true},"newClient":{"description":"Creates a new client inline instead of using an existing one — alternative to client. Prohibited on a request-type assignment unless the same payload approves the request (requestStatus.id).","properties":{"name":{"type":"string","example":"Acme Corp"},"email":{"type":"string","format":"email","example":"contact@acme.test"},"contactName":{"type":"string","example":"Jane Roe"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"phoneExtension":{"type":"string","example":"123","nullable":true},"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"consumer":{"description":"Consumers on the assignment. A single object is also accepted and treated as a one-item list.","type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"},"label":{"type":"string","example":"Consumer Name"}},"type":"object"},"nullable":true},"newConsumer":{"properties":{"name":{"type":"string","example":"Pat Doe"},"email":{"type":"string","format":"email","example":"pat@example.test","nullable":true},"phone":{"type":"string","example":"1234567890","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phoneExtension":{"type":"string","example":"123","nullable":true},"hearingStatus":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}}},"type":"object","nullable":true},"location":{"description":"Required (locationType) when isPublished=true and the assignment has no stored location. Changing locationType away from one with assigned providers is rejected.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"Also accepted at the top level as billingOrganizationLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"Also accepted at the top level as billingClientLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Defaults to primary. Also accepted at the top level as billingOption; the nested value wins if both are sent.","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"manualLocationContact":{"properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"serviceTypes":{"description":"Removing a provider type that already has assigned providers is rejected (see location.onsite.serviceTypeBreakdown).","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"Reducing totalProviders below the number of providers already assigned to that provider type is rejected.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"meetingPlatform":{"type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"billingOrganizationLocationId":{"type":"string","example":"1","nullable":true},"billingClientLocationId":{"type":"string","example":"1","nullable":true},"billingOption":{"type":"string","example":"primary","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"scheduleType":{"type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring","nullable":true},"oneTime":{"description":"Read only when scheduleType=one_time. Changing dateTimeSlots on a completed/past/canceled assignment with no linked finance documents is rejected.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"multiDay":{"description":"Read only when scheduleType=multi_day. Same restriction as oneTime.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"recurring":{"description":"Read only when scheduleType=recurring. Same restriction as oneTime.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Priority Label"}},"type":"object","nullable":true},"status":{"description":"Prohibited on a request-type assignment unless the same payload approves the request. Terminal once in the canceled tree. Away from completed/final/past is restricted to No-Show or Canceled.","properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Status Label"}},"type":"object","nullable":true},"requestStatus":{"description":"Setting this to the 'approved' status id converts a request into a real assignment (and its child requests), allowing client/newClient/status/assignProviders in the same payload.","properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Request Status Label"}},"type":"object","nullable":true},"requestNotApprovedReason":{"type":"string","example":"Requested provider is unavailable for this window.","nullable":true},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object","nullable":true},"broadcast":{"properties":{"id":{"type":"string","example":"on"},"label":{"type":"string","example":"On"}},"type":"object","nullable":true},"broadcastNotify":{"type":"boolean","example":true,"nullable":true},"broadcastAudience":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"}},"type":"object"},"nullable":true},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the assignment","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client/consumer","nullable":true},"allowPartialCoverage":{"type":"boolean","example":true,"nullable":true},"partialDuration":{"description":"Partial coverage windows (required when allowPartialCoverage is true). Omit to keep the assignment's existing windows.","type":"array","items":{"properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-01"},"startTime":{"type":"string","example":"09:00"},"endTime":{"type":"string","example":"10:00"}},"type":"object"},"nullable":true},"assignmentMethod":{"type":"string","enum":["direct","accept","interest"],"example":"direct","nullable":true},"enableBroadcastBestMatch":{"type":"boolean","example":true,"nullable":true},"assignProviders":{"description":"Omit to keep the assignment's currently assigned providers.","type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"serviceType":{"type":"integer","example":1},"locationType":{"type":"string","enum":["onsite","remote"],"example":"onsite"},"serviceProviderType":{"description":"Provider type the provider fills. Inferred when the service type has only one.","type":"integer","example":2,"nullable":true},"partialReason":{"description":"Why a partly matching provider was assigned anyway.","type":"string","nullable":true},"notAvailableReason":{"description":"Why an unavailable provider was assigned anyway.","type":"string","nullable":true},"visibilityReason":{"description":"How the provider came to be listed. Defaults to partial_match_allowed when partialReason is sent, else full_match.","type":"string","example":"client_selected","nullable":true}},"type":"object"},"nullable":true},"overrideSingleRate":{"type":"boolean","example":true,"nullable":true},"overrideBufferTime":{"type":"boolean","example":true,"nullable":true},"overrideClientPreference":{"type":"boolean","example":true,"nullable":true},"clientPreferences":{"description":"Which of the client's stored requirements and preferences the scheduler overrode on this work item. Each flag set to true means that kind is overridden. Stored as sent.","properties":{"clearance":{"type":"boolean","nullable":true},"skill":{"type":"boolean","nullable":true},"certifications":{"type":"boolean","nullable":true},"specialization":{"type":"boolean","nullable":true},"gender":{"type":"boolean","nullable":true},"restrictedServiceProvider":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"preferredServiceProvider":{"type":"boolean","nullable":true}},"type":"object"},"overrideConsumerPreferences":{"description":"Accepted, but not currently saved on update.","type":"boolean","example":true,"nullable":true},"consumerPreferences":{"description":"The same override flags for the consumer's stored requirements and preferences. Stored as sent.","properties":{"clearance":{"type":"boolean","nullable":true},"skill":{"type":"boolean","nullable":true},"certifications":{"type":"boolean","nullable":true},"specialization":{"type":"boolean","nullable":true},"gender":{"type":"boolean","nullable":true},"restrictedServiceProvider":{"type":"boolean","nullable":true},"restrictedClients":{"type":"boolean","nullable":true},"preferredServiceProvider":{"type":"boolean","nullable":true}},"type":"object"},"overrideServiceProviderPreference":{"type":"boolean","example":true,"nullable":true},"serviceProviderPreferences":{"description":"Provider-side rules the scheduler overrode on this work item. Stored as sent.","properties":{"overrideBufferTime":{"type":"boolean","nullable":true},"onSite":{"type":"boolean","nullable":true},"remote":{"type":"boolean","nullable":true},"assignmentLimits":{"type":"boolean","nullable":true},"availability":{"type":"boolean","nullable":true},"locationDistance":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"restrictedClients":{"type":"boolean","nullable":true},"restrictedServiceProviders":{"type":"boolean","nullable":true},"preferredConsumers":{"type":"boolean","nullable":true},"preferredClients":{"type":"boolean","nullable":true},"preferredServiceProviders":{"type":"boolean","nullable":true}},"type":"object"},"requireVerifiedTimeDocumentation":{"type":"boolean","example":false,"nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"},"nullable":true},"providerExpenses":{"description":"Provider expenses.","type":"array","items":{"description":"Expenses for one provider on a work item. Only providers currently assigned to the work item are processed.","required":["providerId"],"properties":{"entityId":{"description":"Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved.","type":"string","example":"ASG-SA2IVL","nullable":true},"providerId":{"type":"string","example":"SPR-H6OUI3"},"expenses":{"type":"array","items":{"required":["name"],"properties":{"id":{"description":"Existing expense id to update; omit to create.","type":"integer","example":42,"nullable":true},"name":{"type":"string","example":"Parking"},"amount":{"type":"number","minimum":0.01,"example":12.5,"nullable":true},"expense":{"description":"Unit amount, multiplied by quantity.","type":"number","minimum":0.01,"example":12.5,"nullable":true},"quantity":{"type":"number","minimum":0.01,"example":1,"nullable":true},"billTo":{"type":"string","enum":["organization","client"],"example":"organization","nullable":true},"document":{"description":"Receipt: pdf, jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isDefault":{"type":"boolean","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom expense.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"nullable":true},"rate":{"description":"Required when reimbursement_basic is percentage.","type":"number","minimum":0,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}}},"type":"object"},"nullable":true},"invoiceStatus":{"properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"payStatus":{"properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"estimatedCost":{"description":"Client-calculated rate preview. Saving is skipped on a completed/past assignment unless the slot time actually changed or finance documents are already linked.","type":"object","nullable":true},"requirementAndPreferences":{"description":"Ignored when quickAssignment is true; the quick flow builds the rows from quickServiceTypes and quickServiceProviderTypes.","type":"array","items":{"description":"Requirements and preferences for one service type on a work item. Rows without serviceType.id are skipped; the list replaces what is stored.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderCertifications":{"description":"Provider type, optionally with a certification it must hold. Pairs that do not belong to the service type are skipped.","type":"array","items":{"properties":{"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certifications":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"skillLevel":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"clearances":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"genderPreference":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"quickAssignment":{"description":"Rebuild requirements from quickServiceTypes and quickServiceProviderTypes.","type":"boolean","example":false,"nullable":true},"quickServiceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true},"quickServiceProviderTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true},"customFields":{"description":"Omitted fields are carried forward from what is already stored, so a partial edit never wipes previously saved custom field values.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"properties":{"id":{"description":"Existing document id — omit file when updating an existing document's metadata only.","type":"integer","nullable":true},"file":{"description":"Required unless id is sent.","type":"string","format":"binary"},"fileName":{"type":"string","example":"intake-form.pdf"}},"type":"object"},"nullable":true},"affectFinancials":{"description":"When a no-show finance sync fails, true re-throws the error instead of saving the no-show selection silently.","type":"boolean","nullable":true},"noshowStatusReason":{"description":"Required when status is being set to a No-Show status. Every participant not named here is cleared of their no-show flag.","type":"array","items":{"properties":{"clients":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"noShowFee":{"type":"number","example":50,"nullable":true}},"type":"object"}},"consumers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"}},"type":"object"}},"providers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"}},"type":"object"}},"reason":{"type":"string","example":"Did not attend"}},"type":"object"},"nullable":true},"cancellationDetails":{"description":"cancellationReason/cancellationCausedBy/billableForCancellation/billCancellationClient/payCancellationProvider are also accepted flat at the top level; the nested value under cancellationDetails wins if both are sent.","properties":{"cancellationReason":{"type":"string","example":"Client requested cancellation"},"cancellationCausedBy":{"description":"Who caused the cancellation, as a label or a {id, label} object.","oneOf":[{"type":"string","example":"client"},{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}]},"cancellationCausedByClient":{"description":"The client or clients responsible, when the cause is a client: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"cancellationCausedByProvider":{"description":"The provider or providers responsible, when the cause is a provider: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"billableForCancellation":{"type":"boolean","example":true},"billCancellationClient":{"description":"When billableForCancellation is true, at least one of billCancellationClient/payCancellationProvider must also be true.","type":"boolean","example":true},"payCancellationProvider":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"responses":{"200":{"description":"Assignment updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"description":"The main message; varies by what changed (e.g. a request-approval conversion message).","type":"string","example":"Assignment updated successfully"},"data":{"properties":{"id":{"type":"string","example":"ASG-SA2IVL"},"messages":{"description":"Secondary notices about the save (e.g. providers that could not be re-attached).","type":"array","items":{"type":"string"}},"workItemFinancialsOutOfSync":{"description":"Present when affectFinancials=false was sent but the change actually affects billed amounts.","type":"boolean","nullable":true},"noShowFinanceSync":{"description":"Present when a no-show selection changed.","type":"object","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Assignment updation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignments/{id}/financial-summary":{"get":{"tags":["Assignments"],"summary":"Get financial summary for an assignment","description":"**Required scope:** `assignments:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves comprehensive financial data including client charges, provider compensation, and profit/loss for a specific assignment or shift.","operationId":"ext_get_assignments_By_id_financial_summary","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"Assignment ID (ASG-XXX) or Shift ID (SFT-XXX)","required":true,"schema":{"type":"string"}},{"name":"clientsPage","in":"query","description":"Page of the clients breakdown (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"clientsPerPage","in":"query","description":"Rows per page of the clients breakdown, 1 to 100.","required":false,"schema":{"type":"integer","example":10}},{"name":"providersPage","in":"query","description":"Page of the providers breakdown (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"providersPerPage","in":"query","description":"Rows per page of the providers breakdown, 1 to 100.","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Financial summary retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Financial summary retrieved successfully"},"data":{"properties":{"clientChargesSummary":{"properties":{"description":{"type":"string","example":"Short human-readable description."},"clients":{"type":"array","items":{"type":"object"}},"totalBilledToClients":{"type":"number","format":"float","example":120.5}},"type":"object"},"providerCompensationSummary":{"properties":{"description":{"type":"string","example":"Short human-readable description."},"providers":{"type":"array","items":{"type":"object"}},"totalProviderPayouts":{"type":"number","format":"float","example":120.5}},"type":"object"},"financialOutcome":{"properties":{"totalRevenue":{"type":"number","format":"float","example":120.5},"totalProviderPayouts":{"type":"number","format":"float","example":120.5},"netProfitLoss":{"type":"number","format":"float","example":120.5},"adminFee":{"description":"Organization/scheduler admin fee included in totalRevenue","type":"number","format":"float","example":120.5},"providerAdminFee":{"description":"Provider admin fee included in totalProviderPayouts","type":"number","format":"float","example":120.5},"totalAdminFee":{"description":"adminFee + providerAdminFee","type":"number","format":"float","example":120.5}},"type":"object"},"linkedFinanceDocuments":{"properties":{"active":{"type":"object"},"historical":{"type":"object"}},"type":"object"},"providerNoShowFinance":{"type":"object"},"missingActiveInvoice":{"type":"boolean","example":true},"missingActivePayable":{"type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized - User does not have permission to view financial data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment or Shift not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read finance:read","x-fido-module":"assignments","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/assignments/{id}/handshakes":{"get":{"tags":["Handshakes"],"summary":"List handshakes for one assignment","description":"**Required scope:** `handshakes:read`  \n**Roles:** admin, scheduler\n\nEvery handshake raised against the given assignment, in full detail rather than list form.","operationId":"ext_get_assignments_By_id_handshakes","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Assignment ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Handshakes retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Handshakes retrieved successfully."},"data":{"type":"array","items":{"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:read","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invitations to an assignment","x-fido-area-rank":2}},"/v1/assignments/{id}/handshakes/invite":{"post":{"tags":["Handshakes"],"summary":"Invite providers to an assignment","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nCreates a handshake per provider and dispatches invite notifications to each. Providers already invited to this assignment are skipped.","operationId":"ext_post_assignments_By_id_handshakes_invite","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Assignment ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["providerIds"],"properties":{"providerIds":{"description":"Service provider IDs to invite.","type":"array","items":{"type":"string","example":"SP-9F2K1A"},"minItems":1}},"type":"object"}}}},"responses":{"201":{"description":"Providers invited.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"2 provider(s) invited successfully."},"data":{"type":"array","items":{"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed — providerIds is required and must contain at least one ID.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invitations to an assignment","x-fido-area-rank":2}},"/v1/audits":{"get":{"tags":["History & Logs"],"summary":"Retrieve audit logs","description":"**Required scope:** `history_logs:read`\n\nFetches a paginated list of audit trail records with filters such as module, user, entity, audit event type, and date range.","operationId":"ext_get_audits","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-DRAS9XNH"}},{"name":"module","in":"query","description":"Filter by module. Accepted values: assignment, shift, client, consumer, service_provider (or service-provider), finance (or finances), organization, settings, broadcast, forms, fido, admin-scheduler.","schema":{"type":"string","enum":["assignment","shift","client","consumer","service_provider","service-provider","finance","finances","organization","settings","broadcast","forms","fido","admin-scheduler"],"example":"assignment"}},{"name":"userId","in":"query","description":"Filter by user ID who performed the action","schema":{"type":"string"}},{"name":"role","in":"query","description":"Filter by actor role (admin, client, consumer, service-provider)","schema":{"type":"string"}},{"name":"auditEventType","in":"query","description":"Filter by audit event type (created, updated, deleted, status_changed, etc.)","schema":{"type":"string","example":"updated"}},{"name":"auditableType","in":"query","description":"Fully qualified auditable model type","schema":{"type":"string","example":"Client"}},{"name":"auditableId","in":"query","description":"ID of the auditable entity","schema":{"type":"string"}},{"name":"from","in":"query","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"End date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"search","in":"query","description":"Search term across audit message & metadata","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort by field (default: created_at)","schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort order (asc or desc)","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Records per page (default: 10)","schema":{"type":"integer"}},{"name":"page","in":"query","description":"Page number (default: 1)","schema":{"type":"integer","example":1}},{"name":"startDate","in":"query","description":"Alias of `from`; read only when `from` is absent.","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"Alias of `to`; read only when `to` is absent.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Audit logs retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"event":{"description":"User-friendly event label","type":"string","example":"Status changed"},"category":{"type":"string","nullable":true},"module":{"type":"string"},"summary":{"description":"Human-readable description of what happened","type":"string","example":"Assignment status changed from Pending to Confirmed."},"description":{"type":"string","example":"Short human-readable description."},"occurredAt":{"type":"string","example":"2026-01-15 09:00:00"},"occurredAtUtc":{"type":"string"},"occurredAtIso":{"type":"string","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"actor":{"description":"Who initiated the action","properties":{"name":{"type":"string","example":"Example name"},"role":{"type":"string","example":"Administrator"},"type":{"description":"Canonical actor type label","type":"string","example":"Administrator"},"image":{"type":"string","nullable":true}},"type":"object"},"subject":{"description":"Whose record was acted on, when distinct from the actor","properties":{"name":{"type":"string","example":"Example name"},"role":{"type":"string","example":"admin"},"image":{"type":"string","nullable":true}},"type":"object","nullable":true},"initiation":{"description":"Manual / Automated / System-generated","type":"string","example":"Manual"},"trigger":{"type":"string","nullable":true},"impersonation":{"properties":{"active":{"type":"boolean","example":true},"impersonator":{"type":"object"},"target":{"type":"object"},"startedAt":{"type":"string","example":"2026-01-15 09:00:00","nullable":true}},"type":"object","nullable":true},"entity":{"properties":{"type":{"type":"string","example":"Assignment"},"reference":{"type":"string","example":"ASN-12345","nullable":true},"label":{"type":"string","example":"Tuesday morning interpretation","nullable":true}},"type":"object"},"changes":{"description":"What changed (humanized field labels, FK ints resolved, PHI redacted for non-privileged viewers)","type":"array","items":{"properties":{"field":{"type":"string","example":"Status"},"from":{"type":"string","example":"Pending"},"to":{"type":"string","example":"Confirmed"}},"type":"object"}},"eventLabel":{"type":"string","example":"Example label"},"auditableType":{"type":"string","example":"App\\\\Models\\\\Assignment"},"auditableId":{"type":"string","example":"ASG-XY9EML"},"oldValues":{"type":"array","items":[]},"newValues":{"type":"array","items":[]},"logMessage":{"type":"string","example":"Request processed successfully."},"actionSource":{"type":"string","example":"manual","nullable":true},"actorType":{"properties":{"code":{"type":"string","nullable":true},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"user":{"properties":{"name":{"type":"string","example":"Example name"},"role":{"type":"string","example":"admin"},"type":{"type":"string"},"image":{"type":"string","example":"https://cdn.example.com/image.png"}},"type":"object","nullable":true},"subjectUser":{"properties":{"name":{"type":"string","example":"Example name","nullable":true},"role":{"type":"string","example":"admin","nullable":true},"type":{"type":"string","nullable":true},"image":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true}},"type":"object","nullable":true},"time":{"type":"string","example":"09:00:00"},"convertedTime":{"type":"string","example":"09:00:00"},"createdAt":{"type":"string","example":"2026-01-15 09:00:00","nullable":true},"internal":{"description":"Only populated for admin/scheduler/super-admin roles — contains raw codes for support & filtering.","type":"object","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":1},"total":{"type":"integer","example":1},"startDate":{"type":"string","example":"2026-01-15"},"endDate":{"type":"string","example":"2026-01-15"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'history_logs:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"history_logs:read","x-fido-module":"history_logs","x-fido-roles":[],"x-fido-area":"Audits","x-fido-area-rank":0}},"/v1/audits/export":{"get":{"tags":["History & Logs"],"summary":"Export audit logs to XLSX","description":"**Required scope:** `history_logs:read`  \n**Roles:** admin, scheduler\n\nExports audit logs to an XLSX file. Supports the same filters as audit listing.","operationId":"ext_get_audits_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string","example":"TNT-DRAS9XNH"}}],"responses":{"200":{"description":"XLSX file containing audit logs","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'history_logs:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"history_logs:read","x-fido-module":"history_logs","x-fido-roles":["admin","scheduler"],"x-fido-area":"Audits","x-fido-area-rank":0}},"/v1/audits/{type}/{id}":{"get":{"tags":["History & Logs"],"summary":"Retrieve audit history for a specific entity","description":"**Required scope:** `history_logs:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated audit trail for a specific entity (client, consumer, service provider, assignment, shift, etc.).","operationId":"ext_get_audits_By_type_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-DRAS9XNH"}},{"name":"type","in":"path","description":"Fully qualified model name of the auditable entity","required":true,"schema":{"type":"string","example":"Client"}},{"name":"id","in":"path","description":"ID of the auditable entity","required":true,"schema":{"type":"string","example":"123"}},{"name":"auditEventType","in":"query","description":"Filter by audit event type (created, updated, deleted, status_changed, etc.)","required":false,"schema":{"type":"string","example":"updated"}},{"name":"from","in":"query","description":"Start date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"End date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"search","in":"query","description":"Search term across audit message and metadata","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort by field (default: created_at)","required":false,"schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Records per page (default: 10)","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Audit history retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"description":"Same shape as /v1/audits. See the listing endpoint for the full property list.","properties":{"id":{"type":"integer","example":1},"event":{"type":"string"},"category":{"type":"string","nullable":true},"module":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string","example":"Short human-readable description."},"occurredAt":{"type":"string","example":"2026-01-15 09:00:00"},"occurredAtUtc":{"type":"string"},"occurredAtIso":{"type":"string","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"actor":{"properties":{"name":{"type":"string","example":"Example name"},"role":{"type":"string","example":"admin"},"type":{"type":"string"},"image":{"type":"string","example":"https://cdn.example.com/image.png"}},"type":"object","nullable":true},"subject":{"properties":{"name":{"type":"string","example":"Example name","nullable":true},"role":{"type":"string","example":"admin","nullable":true},"type":{"type":"string","nullable":true},"image":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true}},"type":"object","nullable":true},"initiation":{"type":"string","nullable":true},"trigger":{"type":"string","nullable":true},"impersonation":{"properties":{"active":{"type":"boolean","example":true},"impersonator":{"type":"object"},"target":{"type":"object"},"startedAt":{"type":"string","example":"2026-01-15 09:00:00","nullable":true}},"type":"object","nullable":true},"entity":{"properties":{"type":{"type":"string"},"reference":{"type":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"changes":{"type":"array","items":[]},"eventLabel":{"type":"string","example":"Example label"},"auditableType":{"type":"string","example":"App\\\\Models\\\\Assignment"},"auditableId":{"type":"string","example":"ASG-XY9EML"},"oldValues":{"type":"array","items":[]},"newValues":{"type":"array","items":[]},"logMessage":{"type":"string","example":"Request processed successfully."},"actionSource":{"type":"string","example":"manual","nullable":true},"actorType":{"properties":{"code":{"type":"string","nullable":true},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"user":{"properties":{"name":{"type":"string","example":"Example name"},"role":{"type":"string","example":"admin"},"type":{"type":"string"},"image":{"type":"string","example":"https://cdn.example.com/image.png"}},"type":"object","nullable":true},"subjectUser":{"properties":{"name":{"type":"string","example":"Example name","nullable":true},"role":{"type":"string","example":"admin","nullable":true},"type":{"type":"string","nullable":true},"image":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true}},"type":"object","nullable":true},"time":{"type":"string","example":"09:00:00"},"convertedTime":{"type":"string","example":"09:00:00"},"createdAt":{"type":"string","example":"2026-01-15 09:00:00","nullable":true},"internal":{"properties":{"auditEventType":{"type":"string","nullable":true},"rawEvent":{"type":"string"},"auditableType":{"type":"string","example":"App\\\\Models\\\\Assignment"},"auditableId":{"type":"string","example":"ASG-XY9EML"},"triggerCode":{"type":"string","nullable":true},"actorTypeCode":{"type":"string","nullable":true},"actorUserId":{"type":"string","example":"USR-LBW3CV","nullable":true},"actorEmail":{"type":"string","example":"user@example.com","nullable":true},"subjectUserId":{"type":"string","nullable":true},"subjectEmail":{"type":"string","example":"user@example.com","nullable":true},"impersonation":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":27}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'history_logs:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Auditable entity not found"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"history_logs:read","x-fido-module":"history_logs","x-fido-roles":["admin","scheduler"],"x-fido-area":"Audits","x-fido-area-rank":0}},"/v1/block-list":{"get":{"tags":["Settings · Restricted Users"],"summary":"Retrieve paginated block list with optional filters","description":"**Required scope:** `settings_restricted_users:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of block list entries. Allows filtering, searching, and sorting.","operationId":"ext_get_block_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search keyword","schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated list of searchable columns","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Column to sort by","schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Items per page","schema":{"type":"integer"}},{"name":"clientId","in":"query","description":"Filter by client ID","schema":{"type":"string"}},{"name":"consumerId","in":"query","description":"Filter by consumer ID","schema":{"type":"string"}},{"name":"serviceProviderId","in":"query","description":"Filter by service provider ID","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":null}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"blockedUser":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label","nullable":true},"onlineStatus":{"type":"string","example":"online"}},"type":"object","nullable":true},"blockedUserRoleName":{"type":"string","example":"admin","nullable":true},"blockedUserImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"blockedUserOnlineStatus":{"type":"string","example":"online"},"blockedRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"notes":{"type":"string","example":"Added by the scheduler."},"blockedDate":{"type":"string","example":"2026-01-15"},"isBehalfOfOrg":{"type":"boolean","example":true},"isBehalfOfRole":{"type":"string","nullable":true},"providerServices":{"type":"array","items":[],"nullable":true},"blockedBy":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object","nullable":true},"blockedByOnlineStatus":{"type":"string","example":"online"},"blockedByRoleName":{"type":"string","example":"admin","nullable":true},"blockedByRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"blockedByImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"blockedByProviderServices":{"type":"array","items":[],"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"object","example":{"search":["Invalid search parameter"]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:read","x-fido-module":"settings_restricted_users","x-fido-roles":["admin","scheduler"],"x-fido-area":"Restricted list","x-fido-area-rank":0},"post":{"tags":["Settings · Restricted Users"],"summary":"Create a new block list entry","description":"**Required scope:** `settings_restricted_users:write`  \n**Roles:** admin, scheduler\n\nCreates a new block list record by specifying the user initiating the block and the user being blocked.","operationId":"ext_post_block_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["blockedBy","blockedUser"],"properties":{"blockedBy":{"required":["id","label"],"properties":{"id":{"type":"string","example":"CLT-EDFFGJ"},"label":{"type":"string","example":"Client"}},"type":"object"},"blockedUser":{"required":["id","label"],"properties":{"id":{"type":"string","example":"CSM-5W5RVY"},"label":{"type":"string","example":"Consumer"}},"type":"object"},"notes":{"type":"string","example":"Demo","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List created!"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to create."},"errors":{"type":"object","example":{"blockedBy.id":["The blockedBy ID field is required."],"blockedUser.id":["The blockedUser ID field is required."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected server error","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:write","x-fido-module":"settings_restricted_users","x-fido-roles":["admin","scheduler"],"x-fido-area":"Restricted list","x-fido-area-rank":0}},"/v1/block-list-export":{"get":{"tags":["Settings · Restricted Users"],"summary":"Export block list to Excel","description":"**Required scope:** `settings_restricted_users:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports the complete block list to an Excel file for download.","operationId":"ext_get_block_list_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing block list data","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:read","x-fido-module":"settings_restricted_users","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Restricted list","x-fido-area-rank":0}},"/v1/block-list/{block_list}":{"delete":{"tags":["Settings · Restricted Users"],"summary":"Delete a block list entry","description":"**Required scope:** `settings_restricted_users:delete`\n\nDeletes a block list entry by its ID. If the ID does not exist, a 404 error will be returned.","operationId":"ext_delete_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"The ID of the block list entry to delete","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List entry deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Block List entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected server error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:delete","x-fido-module":"settings_restricted_users","x-fido-roles":[],"x-fido-area":"Restricted list","x-fido-area-rank":0},"get":{"tags":["Settings · Restricted Users"],"summary":"Retrieve a single block list entry by ID","description":"**Required scope:** `settings_restricted_users:read`  \n**Roles:** admin, scheduler\n\nReturns details of a specific block list entry including who blocked whom, their roles, profile images, notes, and date.","operationId":"ext_get_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"The ID of the block list entry","required":true,"schema":{"type":"integer","example":5}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Block List entry retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List entry retrieved."},"data":{"properties":{"id":{"type":"integer","example":1},"blockedUser":{"properties":{"id":{"type":"string","example":"CSM-5W5RVY"},"label":{"type":"string","example":"ABC"}},"type":"object"},"blockedUserRoleName":{"type":"string","example":"admin","nullable":true},"blockedRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"blockedUserImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"blockedUserOnlineStatus":{"type":"string","example":"online"},"notes":{"type":"string","example":"Added by the scheduler."},"isBehalfOfOrg":{"type":"boolean","example":true},"blockedBy":{"properties":{"id":{"type":"string","example":"CLT-EDFFGJ"},"label":{"type":"string","example":"ABCD"}},"type":"object"},"blockedByOnlineStatus":{"type":"string","example":"online"},"blockedByRoleName":{"type":"string","example":"admin","nullable":true},"blockedByRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"blockedByImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Block List entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Block List entry not found."},"errors":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:read","x-fido-module":"settings_restricted_users","x-fido-roles":["admin","scheduler"],"x-fido-area":"Restricted list","x-fido-area-rank":0},"put":{"tags":["Settings · Restricted Users"],"summary":"Update a block list entry","description":"**Required scope:** `settings_restricted_users:edit`  \n**Roles:** admin, scheduler\n\nPartially update a block list entry. Supports updating the 'blockedBy', 'blockedUser', and 'notes' fields.","operationId":"ext_put_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"ID of the block list entry to update","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"blockedBy":{"properties":{"id":{"description":"ID of the user performing the block","type":"string","example":"CLT-EDFFGJ"},"label":{"description":"Label of the user performing the block","type":"string","example":"Client"}},"type":"object","nullable":true},"blockedUser":{"properties":{"id":{"description":"ID of the user being blocked","type":"string","example":"CSM-5W5RVY"},"label":{"description":"Label of the user being blocked","type":"string","example":"Consumer"}},"type":"object","nullable":true},"notes":{"description":"Optional notes","type":"string","example":"Updated reason for blocking","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Successfully updated block list entry","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List updated successfully."}},"type":"object"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to update."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Block List entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Blocked user entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Block list update failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:edit","x-fido-module":"settings_restricted_users","x-fido-roles":["admin","scheduler"],"x-fido-area":"Restricted list","x-fido-area-rank":0},"patch":{"tags":["Settings · Restricted Users"],"summary":"Update a block list entry","description":"**Required scope:** `settings_restricted_users:edit`  \n**Roles:** admin, scheduler\n\nPartially update a block list entry. Supports updating the 'blockedBy', 'blockedUser', and 'notes' fields.","operationId":"ext_patch_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"ID of the block list entry to update","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"blockedBy":{"properties":{"id":{"description":"ID of the user performing the block","type":"string","example":"CLT-EDFFGJ"},"label":{"description":"Label of the user performing the block","type":"string","example":"Client"}},"type":"object","nullable":true},"blockedUser":{"properties":{"id":{"description":"ID of the user being blocked","type":"string","example":"CSM-5W5RVY"},"label":{"description":"Label of the user being blocked","type":"string","example":"Consumer"}},"type":"object","nullable":true},"notes":{"description":"Optional notes","type":"string","example":"Updated reason for blocking","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Successfully updated block list entry","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List updated successfully."}},"type":"object"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to update."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Block List entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Blocked user entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Block list update failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:edit","x-fido-module":"settings_restricted_users","x-fido-roles":["admin","scheduler"],"x-fido-area":"Restricted list","x-fido-area-rank":0}},"/v1/categories":{"get":{"tags":["Settings · General"],"summary":"Retrieve all Categories or filter by tenant ID","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a list of all Categories or filter by a specific tenant ID if provided.","operationId":"ext_get_categories","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"tenantId","in":"query","description":"Tenant ID. Used for multi-tenant filtering.","required":false,"schema":{"type":"string","example":"demotenant"}}],"responses":{"200":{"description":"Categories retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Categories Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Categories Retrieved!","data":[{"id":1,"value":1,"label":"Example label","isCustom":true}]}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Categories","x-fido-area-rank":0},"post":{"tags":["Settings · General"],"summary":"Create a new category","description":"**Required scope:** `settings_general:write`  \n**Roles:** admin, scheduler\n\nCreate a new category with a name and optional tenant ID.","operationId":"ext_post_categories","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","tenant_id"],"properties":{"name":{"type":"string","example":"Tech category"},"tenant_id":{"type":"string","example":"demotenant"}},"type":"object"}}}},"responses":{"201":{"description":"category created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"category created!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"category created!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Categories","x-fido-area-rank":0}},"/v1/categories/{category}":{"delete":{"tags":["Settings · General"],"summary":"Delete a category by id alone (always 422)","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\n**Use `/v1/categories/{id}/{label}` instead.** This id-only form is registered by the resource route, but the handler identifies the record from a `label` path segment this route does not carry, so the call always fails validation with `label` required.","operationId":"ext_delete_categories_By_category","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"category","in":"path","description":"ID of the category.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed: the category type could not be resolved from the URL.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The label field is required."}},"type":"object"},"example":{"status":"error","message":"The label field is required."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Categories","x-fido-area-rank":0},"put":{"tags":["Settings · General"],"summary":"Update an category","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate an category by ID.","operationId":"ext_put_categories_By_category","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"category","in":"path","description":"ID of the category to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Tech Category"}},"type":"object"}}}},"responses":{"200":{"description":"Category updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Category updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Category updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Category not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Category with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Category with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Categories","x-fido-area-rank":0},"patch":{"tags":["Settings · General"],"summary":"Update an category","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate an category by ID.","operationId":"ext_patch_categories_By_category","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"category","in":"path","description":"ID of the category to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Tech Category"}},"type":"object"}}}},"responses":{"200":{"description":"Category updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Category updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Category updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Category not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Category with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Category with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Categories","x-fido-area-rank":0}},"/v1/categories/{id}/{label}":{"delete":{"tags":["Settings · General"],"summary":"Delete  category","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete category by its ID.","operationId":"ext_delete_categories_By_id_By_label","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"path","description":"ID of the category to delete.","required":true,"schema":{"type":"integer","example":7}},{"name":"label","in":"path","description":"Label of the category to delete.","required":true,"schema":{"type":"string","example":"category"}}],"responses":{"200":{"description":"Category deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Category deleted!"}},"type":"object"},"example":{"success":true,"message":"Category deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Category not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Category with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Category with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Categories","x-fido-area-rank":0}},"/v1/certification-bodies":{"get":{"tags":["Settings · Service Setup"],"summary":"List all certification bodies","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetches all certification bodies and returns them in id-label-value format.","operationId":"ext_get_certification_bodies","responses":{"200":{"description":"Certification Body Fetched Successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Certification Body Fetched Successfully"},"code":{"type":"integer","example":200},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"RID"},"value":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Something went wrong","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Error fetching Certification Bodies: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Certifications","x-fido-area-rank":1}},"/v1/certifications":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve all certifications or filter by tenant ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of certifications, with optional filters including search, sorting, and tenant-specific results.","operationId":"ext_get_certifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant filtering. If not provided, only global certifications are returned.","required":true,"schema":{"type":"string","example":"TNT-QLRJVTKH"}},{"name":"search","in":"query","description":"Search query string to match against name or ID (based on columns).","required":false,"schema":{"type":"string","example":"Custom1"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to apply search on. E.g., name,certificationBody","required":false,"schema":{"type":"string","example":"name,certificationBody"}},{"name":"certificationName","in":"query","description":"Filter by certification name or ID. Accepts both numeric and string inputs.","required":false,"schema":{"type":"string","example":"3"}},{"name":"certificationId","in":"query","description":"Filter by specific certification ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"certificationBody","in":"query","description":"Filter certifications by their certification body ID or name.","required":false,"schema":{"type":"string","example":"7"}},{"name":"requirement","in":"query","description":"Filter by requirement type (e.g., required, optional).","required":false,"schema":{"type":"string","enum":["required","optional"],"example":"optional"}},{"name":"expirationRequired","in":"query","description":"Filter certifications based on whether expiration date is required.","required":false,"schema":{"type":"boolean","example":true}},{"name":"uploadRequired","in":"query","description":"Filter certifications based on whether document upload is required.","required":false,"schema":{"type":"boolean","example":true}},{"name":"sortBy","in":"query","description":"Column to sort by.","required":false,"schema":{"type":"string","default":"name","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order direction (asc or desc).","required":false,"schema":{"type":"string","default":"asc","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Number of results per page.","required":false,"schema":{"type":"integer","default":10,"example":20}}],"responses":{"200":{"description":"Certifications retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"certificationBody":{"type":"integer","example":1,"nullable":true},"certificationBodyName":{"type":"string","example":"Example name","nullable":true},"level":{"type":"integer","example":1,"nullable":true},"requirement":{"type":"string","example":"preferred","nullable":true},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"}}}},"400":{"description":"Invalid request (e.g. bad input type)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"string","example":"Error fetching certifications: SQLSTATE[22P02]..."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"An unexpected error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Certifications","x-fido-area-rank":1},"post":{"tags":["Settings · Service Setup"],"summary":"Create new certifications","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate one or more certifications with optional metadata.","operationId":"ext_post_certifications","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","requirement","serviceType","serviceProviderType"],"properties":{"name":{"type":"array","items":{"required":["label"],"properties":{"label":{"type":"string","example":"New Certification"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"preferred"},"level":{"description":"Position within the certification body. Defaults to the next free level.","type":"integer","minimum":1,"example":1,"nullable":true},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true},"certificationBody":{"description":"An existing body by id, or a new one by label.","properties":{"id":{"type":"integer","example":3,"nullable":true},"label":{"type":"string","example":"CI / CT Basic"},"isCustom":{"type":"boolean","example":false}},"type":"object","nullable":true},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Typist"}},"type":"object"}},"type":"object"}}}},"responses":{"201":{"description":"Certifications created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Certifications created!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":11},"name":{"type":"string","example":"New Certification"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Certifications created!","data":[{"id":11,"name":"New Certification","isCustom":true},{"id":12,"name":"Another One","isCustom":true}]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Certifications","x-fido-area-rank":1}},"/v1/certifications/{certification}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a certification","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a certification by its ID.","operationId":"ext_delete_certifications_By_certification","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"certification","in":"path","description":"ID of the certification to delete.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"200":{"description":"Certification deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Certification deleted!"}},"type":"object"},"example":{"success":true,"message":"Certification deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Certification not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Certification with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Certification with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Certifications","x-fido-area-rank":1},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a specific certifications by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a single certifications record by its ID.","operationId":"ext_get_certifications_By_certification","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"certification","in":"path","description":"ID of the Certifications to retrieve.","required":true,"schema":{"type":"integer","example":3}}],"responses":{"200":{"description":"Certifications retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Certifications Retrieved!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"certificationBody":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"level":{"type":"integer","example":1},"requirement":{"type":"string","example":"preferred"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Certifications Retrieved!","data":{"id":1,"name":{"id":1,"label":"Example label"},"certificationBody":{"id":1,"label":"Example label"},"serviceType":{"id":1,"label":"Example label"},"serviceProviderType":{"id":1,"label":"Example label"},"level":1,"requirement":"preferred","expirationRequired":true,"uploadRequired":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Certifications not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Certifications with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Certifications with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Certifications","x-fido-area-rank":1},"put":{"tags":["Settings · Service Setup"],"summary":"Update a certification","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing certification by ID.","operationId":"ext_put_certifications_By_certification","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"certification","in":"path","description":"ID of the certification to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Certification"},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"required"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":false},"certificationBody":{"description":"Renames the certification body this certification belongs to.","type":"string","example":"Registry Board","nullable":true},"level":{"description":"Moves the certification within its body; null puts it at the next free level.","type":"integer","minimum":1,"example":2,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Certification updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Certification updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"label":{"type":"string","example":"Updated Certification"},"value":{"type":"integer","example":3},"isCustom":{"type":"boolean","example":true},"serviceId":{"type":"integer","example":1}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Certification updated!","data":{"id":3,"label":"Updated Certification","value":3,"isCustom":true,"serviceId":1}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"The name field is required."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"name":["The name field is required."]}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Certification not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Certification with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Certification with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Certifications","x-fido-area-rank":1},"patch":{"tags":["Settings · Service Setup"],"summary":"Update a certification","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing certification by ID.","operationId":"ext_patch_certifications_By_certification","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"certification","in":"path","description":"ID of the certification to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Certification"},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"required"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":false},"certificationBody":{"description":"Renames the certification body this certification belongs to.","type":"string","example":"Registry Board","nullable":true},"level":{"description":"Moves the certification within its body; null puts it at the next free level.","type":"integer","minimum":1,"example":2,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Certification updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Certification updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"label":{"type":"string","example":"Updated Certification"},"value":{"type":"integer","example":3},"isCustom":{"type":"boolean","example":true},"serviceId":{"type":"integer","example":1}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Certification updated!","data":{"id":3,"label":"Updated Certification","value":3,"isCustom":true,"serviceId":1}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"The name field is required."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"name":["The name field is required."]}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Certification not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Certification with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Certification with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Certifications","x-fido-area-rank":1}},"/v1/clearance-bodies":{"get":{"tags":["Settings · Service Setup"],"summary":"List all clearance bodies","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetches all clearance bodies and returns them in id-label-value format.","operationId":"ext_get_clearance_bodies","responses":{"200":{"description":"Clearance Body Fetched Successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Clearance Body Fetched Successfully"},"code":{"type":"integer","example":200},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"FBI"},"value":{"type":"integer","example":2}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Something went wrong","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Error fetching Clearance Bodies: SQLSTATE[HY000] [1049] Unknown database 'clearances_db'","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clearances","x-fido-area-rank":2}},"/v1/clearances":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve all clearances or filter by tenant ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of all clearances with support for search, sorting, and filtering by tenant ID.","operationId":"ext_get_clearances","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant filtering.","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Search term to filter clearances by name.","required":false,"schema":{"type":"string","example":"Top Secret"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to apply search on (e.g., name).","required":false,"schema":{"type":"string","example":"name,clearanceBody"}},{"name":"clearanceId","in":"query","description":"Filter by specific clearance ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"clearanceBody","in":"query","description":"Filter by clearance body ID or name.","required":false,"schema":{"type":"string","example":"2"}},{"name":"requirement","in":"query","description":"Filter by requirement type (e.g., required, optional, mandatory, preferred).","required":false,"schema":{"type":"string","enum":["required","optional","mandatory","preferred"],"example":"optional"}},{"name":"expirationRequired","in":"query","description":"Filter clearances based on whether expiration is required.","required":false,"schema":{"type":"boolean","example":true}},{"name":"uploadRequired","in":"query","description":"Filter clearances based on whether document upload is required.","required":false,"schema":{"type":"boolean","example":true}},{"name":"sortBy","in":"query","description":"Field to sort results by.","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sort order: asc or desc.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of results per page.","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Clearances retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"clearanceBody":{"type":"integer","example":1},"clearanceBodyName":{"type":"string","example":"Example name"},"requirement":{"type":"string","example":"preferred"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"name":"Example name","clearanceBody":1,"clearanceBodyName":"Example name","requirement":"preferred","expirationRequired":true,"uploadRequired":true}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":2}}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clearances","x-fido-area-rank":2},"post":{"tags":["Settings · Service Setup"],"summary":"Create new clearances","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate one or more clearances with optional custom names and body.","operationId":"ext_post_clearances","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["clearanceBody","name"],"properties":{"name":{"type":"array","items":{"required":["label"],"properties":{"id":{"type":"integer","example":null},"label":{"type":"string","example":"DOJ Clearance"}},"type":"object"}},"clearanceBody":{"properties":{"id":{"type":"integer","example":null},"label":{"type":"string","example":"Internal Authority"}},"type":"object"},"requirement":{"type":"string","enum":["mandatory","preferred","optional"],"example":"preferred"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true},"tenant_id":{"type":"string","example":"demotenant","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Clearance(s) created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Clearances created!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"DOJ Clearance"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Clearances created!","data":[{"id":5,"name":"DOJ Clearance","isCustom":true},{"id":6,"name":"asdsads","isCustom":true}]}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Clearance name is required."}},"clearanceBody":{"type":"array","items":{"type":"string","example":"Clearance Body name is already taken."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"name":["Clearance name is required."],"clearanceBody":["Clearance Body name is already taken."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clearances","x-fido-area-rank":2}},"/v1/clearances/{clearance}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a clearance","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a clearance by ID.","operationId":"ext_delete_clearances_By_clearance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"clearance","in":"path","description":"ID of the clearance to delete.","required":true,"schema":{"type":"integer","example":5}}],"responses":{"200":{"description":"Clearance deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Clearance deleted!"}},"type":"object"},"example":{"success":true,"message":"Clearance deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Clearance not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Clearance with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Clearance with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clearances","x-fido-area-rank":2},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a specific clearance by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a single clearance record by its ID.","operationId":"ext_get_clearances_By_clearance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"clearance","in":"path","description":"ID of the clearance to retrieve.","required":true,"schema":{"type":"integer","example":3}}],"responses":{"200":{"description":"Clearance retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Clearance Retrieved!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"isCustom":{"type":"boolean","example":true},"clearanceBody":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"requirement":{"type":"string","example":"preferred"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Clearance Retrieved!","data":{"id":1,"name":{"id":1,"label":"Example label"},"isCustom":true,"clearanceBody":{"id":1,"label":"Example label"},"requirement":"preferred","expirationRequired":true,"uploadRequired":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Clearance not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Clearance with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Clearance with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clearances","x-fido-area-rank":2},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing clearance","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate a clearance record by its ID with optional name changes, flags, and clearance body.","operationId":"ext_put_clearances_By_clearance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"clearance","in":"path","description":"ID of the clearance to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"array","items":{"required":["label"],"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Updated Clearance Name"}},"type":"object"},"example":"Example name"},"clearanceBody":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Federal Bureau"}},"type":"object"},"requirement":{"type":"string","enum":["mandatory","preferred","optional"],"example":"mandatory"},"expirationRequired":{"type":"boolean","example":false},"uploadRequired":{"type":"boolean","example":true},"tenant_id":{"type":"string","example":"demotenant","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Clearance updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Clearance updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Updated Clearance Name"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Clearance updated!","data":{"id":3,"name":"Updated Clearance Name","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Clearance not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Clearance with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Clearance with ID 3 not found."}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Clearance name is required."}},"clearanceBody":{"type":"array","items":{"type":"string","example":"Clearance Body name is already taken."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"name":["Clearance name is required."],"clearanceBody":["Clearance Body name is already taken."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clearances","x-fido-area-rank":2},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing clearance","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate a clearance record by its ID with optional name changes, flags, and clearance body.","operationId":"ext_patch_clearances_By_clearance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"clearance","in":"path","description":"ID of the clearance to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"array","items":{"required":["label"],"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Updated Clearance Name"}},"type":"object"},"example":"Example name"},"clearanceBody":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Federal Bureau"}},"type":"object"},"requirement":{"type":"string","enum":["mandatory","preferred","optional"],"example":"mandatory"},"expirationRequired":{"type":"boolean","example":false},"uploadRequired":{"type":"boolean","example":true},"tenant_id":{"type":"string","example":"demotenant","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Clearance updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Clearance updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Updated Clearance Name"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Clearance updated!","data":{"id":3,"name":"Updated Clearance Name","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Clearance not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Clearance with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Clearance with ID 3 not found."}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Clearance name is required."}},"clearanceBody":{"type":"array","items":{"type":"string","example":"Clearance Body name is already taken."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"name":["Clearance name is required."],"clearanceBody":["Clearance Body name is already taken."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clearances","x-fido-area-rank":2}},"/v1/clients/document/files":{"delete":{"tags":["Clients"],"summary":"Delete files associated with a client","description":"**Required scope:** `clients:edit`  \n**Roles:** admin, client, scheduler\n\nDeletes uploaded files tied to a specific client.","operationId":"ext_delete_clients_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["fileIds"],"properties":{"fileIds":{"description":"Array of client file IDs to delete","type":"array","items":{"type":"integer","example":5}}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully!"}},"type":"object"},"example":{"success":true,"message":"Files deleted successfully!"}}}},"400":{"description":"Bad request - Missing or invalid file ID(s)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid file ID(s) provided."}},"type":"object"},"example":{"success":false,"message":"Invalid file ID(s) provided."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"A client-portal caller attempted to delete a document that isn't theirs, or referenced a document id that doesn't resolve. The message is deliberately generic and does not distinguish the two.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:edit","x-fido-module":"clients","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Clients","x-fido-area-rank":0}},"/v1/clients/export":{"get":{"tags":["Clients"],"summary":"Export clients to Excel","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all clients to an Excel file for download.","operationId":"ext_get_clients_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-NRLWQEDM"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing all clients","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Clients","x-fido-area-rank":0}},"/v1/clients/name-list":{"get":{"tags":["Clients"],"summary":"Get all clients' names and IDs","description":"**Required scope:** `clients:read` or `assignments:read` or `shifts:read` or `schedule:read` or `consumers:read` or `providers:read` or `finance:read` or `forms:read`\n\nFetches a list of all clients with only their ID and name. Optionally filters by published status and includes/excludes locations.","operationId":"ext_get_clients_name_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"withoutLocation","in":"query","description":"Set to true to exclude locations from the response","required":false,"schema":{"type":"boolean","default":false}},{"name":"isActive","in":"query","description":"Filter by active status. If true, only active clients are returned.","required":false,"schema":{"type":"boolean","example":true}},{"name":"isPublished","in":"query","description":"Filter by published status. If true, only published clients are returned. If false, only unpublished clients are returned. If omitted, all clients are returned.","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"List of clients retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Clients fetched successfully!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"value":{"type":"string","example":"1"},"label":{"type":"string","example":"Acme Corp"},"image":{"type":"string","example":"logo.png"},"locations":{"type":"array","items":{"properties":{"id":{"type":"string","example":"101"},"value":{"type":"string","example":"101"},"label":{"type":"string","example":"Acme HQ"}},"type":"object"}}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Clients fetched successfully!","data":[{"id":"1","value":"1","label":"Acme Corp","image":"logo.png","locations":[{"id":"101","value":"101","label":"Acme HQ"}]},{"id":"2","value":"2","label":"Globex Inc","image":null,"locations":[]}]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read|assignments:read|shifts:read|schedule:read|consumers:read|providers:read|finance:read|forms:read","x-fido-module":"clients","x-fido-roles":[],"x-fido-area":"Clients","x-fido-area-rank":0}},"/v1/clients/{client}":{"delete":{"tags":["Clients"],"summary":"Delete a client","description":"**Required scope:** `clients:delete`  \n**Roles:** admin, scheduler\n\nDeletes a specific client by ID. This will remove the client and all associated data such as locations, documents, and preferences.","operationId":"ext_delete_clients_By_client","parameters":[{"name":"client","in":"path","description":"The ID of the client to delete.","required":true,"schema":{"type":"string","example":"CLT-IXRJBO"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Client deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client deleted successfully!"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure the client ID exists."}},"type":"object"},"example":{"success":false,"message":"Invalid parameters. Ensure the client ID exists."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not Found - Client does not exist","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Client not found."}},"type":"object"},"example":{"success":false,"message":"Client not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:delete","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clients","x-fido-area-rank":0},"post":{"tags":["Clients"],"summary":"Update an existing client","description":"**Required scope:** `clients:edit`  \n**Roles:** admin, scheduler\n\nUpdates a client's information, including general data, services, skills, clearances, billing, preferences, and rates.","operationId":"ext_post_clients_By_client","parameters":[{"name":"client","in":"path","description":"The ID of the client to update","required":true,"schema":{"type":"string","example":"CLT-IXRJBO"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Sent as multipart/form-data when a logo, contact image or document is attached; nested objects and lists may then be JSON-encoded strings.","properties":{"name":{"type":"string","maxLength":255,"example":"Acme Health"},"clientType":{"description":"Required on create.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"email":{"description":"Required when portalAccess or networkAccess is true. Unique among clients.","type":"string","format":"email","maxLength":255,"example":"ops@acme.test","nullable":true},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"portalAccess":{"description":"Let the client sign in to the client portal.","type":"boolean","example":false,"nullable":true},"networkAccess":{"description":"Share the client with the Fido network.","type":"boolean","example":false,"nullable":true},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"formId":{"description":"Intake form the client came from.","type":"string","nullable":true},"industry":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"hearingStatus":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateOfBirth":{"type":"string","format":"date","nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"enableCalendarIntegration":{"type":"boolean","nullable":true},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"phoneExtension":{"type":"string","maxLength":10,"example":"204","nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"addressLine1":{"description":"Primary location address.","type":"string","maxLength":255,"example":"123 Main St.","nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"type":"string","maxLength":100,"example":"Dover","nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"12345 or 12345-6789.","type":"string","example":"19901","nullable":true},"accessInstruction":{"type":"string","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"shiftCapacity":{"type":"boolean","example":false,"nullable":true},"minimumCapacity":{"description":"Required when shiftCapacity is true; at most maximumCapacity.","type":"integer","minimum":0,"nullable":true},"maximumCapacity":{"description":"Required when shiftCapacity is true; at least minimumCapacity.","type":"integer","minimum":1,"nullable":true},"billingAddressDifferent":{"type":"boolean","nullable":true},"billingStreetAddress":{"type":"string","nullable":true},"billingStreetAddressLine2":{"type":"string","nullable":true},"billingCity":{"type":"string","nullable":true},"billingState":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billingPostalCode":{"type":"string","nullable":true},"department":{"description":"Primary location contact.","type":"string","maxLength":255,"nullable":true},"contactName":{"type":"string","maxLength":255,"nullable":true},"role":{"type":"string","maxLength":255,"nullable":true},"contactEmail":{"type":"string","format":"email","maxLength":255,"nullable":true},"contactImage":{"description":"jpg, jpeg, png or gif, max 2 MB.","type":"string","format":"binary","nullable":true},"contactPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhone":{"description":"Required when receiveSms is true.","type":"string","nullable":true},"contactPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"contactPhoneExtension":{"type":"string","nullable":true},"contactVideoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"contactVideoPhone":{"type":"string","nullable":true},"assignmentRequest":{"description":"Notification preference.","type":"boolean","nullable":true},"assignmentUpdates":{"description":"Notification preference.","type":"boolean","nullable":true},"allowClientsToBroadcastImmediately":{"description":"The client's requests broadcast without scheduler review.","type":"boolean","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"defaultTimezone":{"description":"Localization.","type":"string","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization.","type":"string","nullable":true},"startOfWeek":{"description":"Localization.","type":"string","example":"monday","nullable":true},"startOfDay":{"description":"Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"Localization.","type":"string","example":"18:00","nullable":true},"preferredServiceLocations":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"associatedConsumer":{"description":"Consumers associated with the client.","type":"array","items":{"properties":{"consumer":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"relationship":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"portalAccess":{"type":"boolean","nullable":true},"allowServiceRequests":{"type":"boolean","nullable":true},"allowAssignmentChanges":{"type":"boolean","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userPreferred":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"customizeRequirementPreferences":{"description":"Per-service-type requirements. true reads requirementAndPreferences; false reads the flat default-tier fields below.","type":"boolean","nullable":true},"serviceTypes":{"description":"Default requirement tier. Service types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderTypes":{"description":"Default requirement tier. Provider roles.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"providerTypes":{"description":"Default requirement tier. Provider types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"description":"Default requirement tier. Minimum skill level.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"genderPreferences":{"description":"Default requirement tier. Preferred provider gender.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"certifications":{"description":"Default requirement tier. Required certifications.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"clearances":{"description":"Default requirement tier. Required clearances.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"specializations":{"description":"Default requirement tier. Required specializations.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedClients":{"description":"Clients this client may not be scheduled with.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientRestricted":{"description":"Client users restricted from this client.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientLocation":{"description":"Existing client location to attach this client to.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]}},"type":"object","nullable":true},"expenses":{"description":"Reimbursable expense categories enabled for this client.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"requirementAndPreferences":{"type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customizeRateBilling":{"description":"Use the client's own rates and billing instead of the organization defaults. Makes billingFrequency and invoiceFrequency required.","type":"boolean","nullable":true},"adminFee":{"type":"number","nullable":true},"adminFeeMethod":{"type":"string","example":"flat","nullable":true},"adminFeeType":{"type":"string","enum":["assignment","shift","both"],"nullable":true},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"},"nullable":true},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"},"nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"applyCancellationFee":{"type":"boolean","nullable":true},"feeType":{"description":"Required when applyCancellationFee is true. full clears feeValue.","type":"string","enum":["full","flat","percentage"],"nullable":true},"feeValue":{"type":"number","minimum":0,"nullable":true},"cancellationWindow":{"description":"Required when applyCancellationFee is true.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"paymentTerm":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"autoGenerateInvoice":{"type":"boolean","nullable":true},"autoSendInvoice":{"type":"boolean","nullable":true},"autoGenerateProForma":{"type":"boolean","nullable":true},"autoSendProForma":{"type":"boolean","nullable":true},"billingFrequency":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"invoiceFrequency":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"proFormaGroupsPerCycle":{"description":"Required with billingFrequency or invoiceFrequency.","type":"integer","maximum":12,"minimum":1,"nullable":true},"beginBillingSchedule":{"description":"Required with billingFrequency or invoiceFrequency.","type":"string","format":"date","nullable":true},"invoiceSendDay":{"description":"Required with billingFrequency or invoiceFrequency.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"proFormaSendSchedule":{"description":"Required with billingFrequency or invoiceFrequency.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"billingResponsibility":{"type":"string","nullable":true},"expenseApprovalAccess":{"type":"boolean","nullable":true},"requireVerifiedTimeDocumentation":{"type":"boolean","nullable":true},"documents":{"description":"pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each.","type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Client updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client Updated!"},"data":{"properties":{"id":{"type":"string","example":"CLT-101"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Client Updated!","data":{"id":"CLT-101"}}}}},"401":{"description":"Unauthorized - Token required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The payload carries a Rates & Billing field (rates, single rates, admin fee, billing and cancellation terms) and the role has no Finance Edit, so nothing is saved. A payload without those fields follows the record's own permission alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A rate unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved. The message is under unit for a rate row, or assignmentRateUnit or shiftRateUnit for a single rate (no row index).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"The name field is required."}},"clientType":{"type":"array","items":{"type":"string","example":"The clientType field is required."}},"status.id":{"type":"array","items":{"type":"string","example":"The status.id field must be an integer."}},"billing.numberOfInvoices":{"type":"array","items":{"type":"string","example":"The numberOfInvoices must be a positive number."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation failed","errors":{"name":["The name field is required."],"clientType":["The clientType field is required."],"status.id":["The status.id field must be an integer."],"billing.numberOfInvoices":["The numberOfInvoices must be a positive number."],"unit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:edit","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clients","x-fido-area-rank":0}},"/v1/clients/{client}/locations":{"get":{"tags":["Clients"],"summary":"Retrieve a list of client locations","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of client locations based on filters like search, client, location, sorting, etc.","operationId":"ext_get_clients_By_client_locations","parameters":[{"name":"search","in":"query","required":false,"schema":{"description":"Search query to filter locations by name, address, city, etc.","type":"string"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"client","in":"path","description":"Unique identifier of the client","required":true,"schema":{"type":"string","example":"CLT-VX6R0"}},{"name":"location","in":"query","required":false,"schema":{"description":"Filter locations by location name.","type":"string"}},{"name":"columns","in":"query","required":false,"schema":{"description":"Search query within visible column content.","type":"string","example":"clientName,address,contact,status"}},{"name":"isPublished","in":"query","description":"Filter clients location by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"status","in":"query","description":"Filter locations by status id (from the statuses lookup table).","required":false,"schema":{"type":"integer","example":1}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter locations created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter locations created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"sortBy","in":"query","required":false,"schema":{"description":"Sort locations by a specific field (e.g., 'name', 'created_at').","type":"string"}},{"name":"sortOrder","in":"query","required":false,"schema":{"description":"Sorting order: ascending ('asc') or descending ('desc').","type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","required":false,"schema":{"description":"Number of locations to retrieve per page.","type":"integer"}}],"responses":{"200":{"description":"Locations retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLTLOC-HQBS7"},"locationName":{"type":"string","example":"Main Office"},"logo":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"addressLine1":{"type":"string","example":"123 Main St","nullable":true},"addressLine2":{"type":"string","example":"Suite 200","nullable":true},"city":{"type":"string","example":"Austin","nullable":true},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"code":{"type":"string"}},"type":"object","nullable":true},"postalCode":{"type":"string","example":"90210","nullable":true},"status":{"type":"integer","example":1,"nullable":true},"statusName":{"type":"string","example":"Active","nullable":true},"isPublished":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true},"isPrimaryAddress":{"type":"boolean","example":true},"department":{"type":"string","example":"Radiology","nullable":true},"contactName":{"type":"string","example":"Jane Smith","nullable":true},"contactImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"contactEmail":{"type":"string","example":"user@example.com","nullable":true},"contactPhone":{"type":"string","example":"+1-555-0142","nullable":true},"contactPhoneExtension":{"type":"string","example":"101","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"client":{"type":"string","example":"CLT-XWB2RY"},"clientName":{"type":"string","example":"Example name","nullable":true},"clientImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"onlineStatus":{"type":"string","example":"online"},"clientEmail":{"type":"string","example":"user@example.com","nullable":true},"clientPhone":{"type":"string","example":"+1-555-0142","nullable":true},"clientType":{"type":"string","example":"Individual","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"},"example":{"success":false,"message":"Invalid parameters. Ensure all required filters are correct."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1},"post":{"tags":["Clients"],"summary":"Create a new client location","description":"**Required scope:** `clients:write`  \n**Roles:** admin, scheduler\n\nCreates a new client location with address, preferences, rates, reimbursable expenses, contact information, and documents. Rates & Billing fields (rates, single rates, admin fee, billing and cancellation terms) need Finance Write: without it they are left out and the new record takes the organization's.","operationId":"ext_post_clients_By_client_locations","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"client","in":"path","description":"Unique identifier of the client","required":true,"schema":{"type":"string","example":"CLT-VX6R0"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Sent as multipart/form-data when a logo, contact image or document is attached.","required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Downtown Office"},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timezone":{"type":"string","example":"America/New_York","nullable":true},"addressLine1":{"type":"string","maxLength":255,"nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"type":"string","maxLength":100,"nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"12345 or 12345-6789.","type":"string","example":"19901","nullable":true},"accessInstruction":{"type":"string","nullable":true},"preferredServiceLocations":{"description":"Onsite, remote or both.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"shiftCapacity":{"type":"boolean","nullable":true},"minimumCapacity":{"description":"At most maximumCapacity.","type":"integer","minimum":0,"nullable":true},"maximumCapacity":{"description":"At least minimumCapacity.","type":"integer","minimum":1,"nullable":true},"department":{"description":"Location contact.","type":"string","maxLength":255,"nullable":true},"contactName":{"type":"string","maxLength":255,"nullable":true},"role":{"type":"string","maxLength":255,"nullable":true},"contactEmail":{"type":"string","format":"email","maxLength":255,"nullable":true},"contactImage":{"description":"jpg, jpeg, png or gif, max 2 MB. Send an empty value to remove the current one.","type":"string","format":"binary","nullable":true},"countryCode":{"description":"Contact phone country code.","type":"string","example":"+1","nullable":true},"contactPhone":{"type":"string","nullable":true},"contactPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"contactPhoneExtension":{"type":"string","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"contactVideoPhone":{"description":"Location contact video phone.","type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gender":{"description":"Required when the location is published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"priority":{"description":"Default priority for work at this location.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"billingAddressDifferent":{"type":"boolean","nullable":true},"billingStreetAddress":{"type":"string","nullable":true},"billingStreetAddressLine2":{"type":"string","nullable":true},"billingCity":{"type":"string","nullable":true},"billingState":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billingPostalCode":{"type":"string","nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"enableCustomRates":{"description":"Use this location's own rates instead of the client's.","type":"boolean","nullable":true},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"},"nullable":true},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"},"nullable":true},"adminFee":{"type":"number","nullable":true},"adminFeeMethod":{"type":"string","example":"flat","nullable":true},"adminFeeType":{"type":"string","enum":["assignment","shift","both"],"nullable":true},"requireVerifiedTimeDocumentation":{"type":"boolean","nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"documents":{"description":"pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each.","type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"isDuplicated":{"description":"Set when this create duplicates an existing location; records a duplication audit event instead of a plain create.","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The location being duplicated. Read only with isDuplicated=true.","type":"string","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Location created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Location created successfully"},"data":{"properties":{"id":{"type":"string","example":"LOC-123"},"clientId":{"type":"string","example":"CLT-ABC123"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Location created successfully","data":{"id":"LOC-123","clientId":"CLT-ABC123"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"properties":{"addressLine1":{"type":"array","items":{"type":"string","example":"The addressLine1 field is required."}},"status":{"type":"array","items":{"type":"string","example":"The status field is required and must include an id."}},"rates.0.serviceId":{"type":"array","items":{"type":"string","example":"The serviceId field is required for each rate."}},"customRates.1.value":{"type":"array","items":{"type":"string","example":"The value must be a number."}},"contactEmail":{"type":"array","items":{"type":"string","example":"The contactEmail must be a valid email address."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation failed","errors":{"addressLine1":["The addressLine1 field is required."],"status":["The status field is required and must include an id."],"rates.0.serviceId":["The serviceId field is required for each rate."],"customRates.1.value":["The value must be a number."],"contactEmail":["The contactEmail must be a valid email address."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"error":{"type":"string","example":"Internal server error."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred — please try again.","error":"Internal server error."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:write","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/clients/{client}/locations/{location}":{"delete":{"tags":["Clients"],"summary":"Delete a client location","description":"**Required scope:** `clients:delete`  \n**Roles:** admin, client, scheduler\n\nDeletes a specific client location by ID. This will remove the location and all associated data such as reimbursable expenses, rates, documents, and preferences tied to that location.","operationId":"ext_delete_clients_By_client_locations_By_location","parameters":[{"name":"location","in":"path","description":"The ID of the client location to delete.","required":true,"schema":{"type":"string","example":"CLTLOC-VX6R0"}},{"name":"client","in":"path","description":"Unique identifier of the client","required":true,"schema":{"type":"string","example":"CLT-VX6R0"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Location deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Location deleted successfully!"},"data":{"properties":{"id":{"type":"string","example":"LOC-WYZ123"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid location ID provided. Ensure the ID is correct and exists."}},"type":"object"},"example":{"success":false,"message":"Invalid location ID provided. Ensure the ID is correct and exists."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"A client-portal caller attempted to delete a location that isn't theirs. The message is deliberately generic and does not confirm whether the location exists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not Found - Client location does not exist","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Client location not found."}},"type":"object"},"example":{"success":false,"message":"Client location not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:delete","x-fido-module":"clients","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1},"post":{"tags":["Clients"],"summary":"Update an existing client location","description":"**Required scope:** `clients:edit`  \n**Roles:** admin, scheduler\n\nUpdates a client location's full details including address, contact, industry, rates, preferences, and documents.","operationId":"ext_post_clients_By_client_locations_By_location","parameters":[{"name":"location","in":"path","description":"The ID of the client location to update","required":true,"schema":{"type":"string","example":"CLTLOC-VX6R0"}},{"name":"client","in":"path","description":"Unique identifier of the client","required":true,"schema":{"type":"string","example":"CLT-VX6R0"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Sent as multipart/form-data when a logo, contact image or document is attached.","properties":{"name":{"type":"string","maxLength":255,"example":"Downtown Office"},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timezone":{"type":"string","example":"America/New_York","nullable":true},"addressLine1":{"type":"string","maxLength":255,"nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"type":"string","maxLength":100,"nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"12345 or 12345-6789.","type":"string","example":"19901","nullable":true},"accessInstruction":{"type":"string","nullable":true},"preferredServiceLocations":{"description":"Onsite, remote or both.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"shiftCapacity":{"type":"boolean","nullable":true},"minimumCapacity":{"description":"At most maximumCapacity.","type":"integer","minimum":0,"nullable":true},"maximumCapacity":{"description":"At least minimumCapacity.","type":"integer","minimum":1,"nullable":true},"department":{"description":"Location contact.","type":"string","maxLength":255,"nullable":true},"contactName":{"type":"string","maxLength":255,"nullable":true},"role":{"type":"string","maxLength":255,"nullable":true},"contactEmail":{"type":"string","format":"email","maxLength":255,"nullable":true},"contactImage":{"description":"jpg, jpeg, png or gif, max 2 MB. Send an empty value to remove the current one.","type":"string","format":"binary","nullable":true},"countryCode":{"description":"Contact phone country code.","type":"string","example":"+1","nullable":true},"contactPhone":{"type":"string","nullable":true},"contactPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"contactPhoneExtension":{"type":"string","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"contactVideoPhone":{"description":"Location contact video phone.","type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gender":{"description":"Required when the location is published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"priority":{"description":"Default priority for work at this location.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"billingAddressDifferent":{"type":"boolean","nullable":true},"billingStreetAddress":{"type":"string","nullable":true},"billingStreetAddressLine2":{"type":"string","nullable":true},"billingCity":{"type":"string","nullable":true},"billingState":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billingPostalCode":{"type":"string","nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"enableCustomRates":{"description":"Use this location's own rates instead of the client's.","type":"boolean","nullable":true},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"},"nullable":true},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"},"nullable":true},"adminFee":{"type":"number","nullable":true},"adminFeeMethod":{"type":"string","example":"flat","nullable":true},"adminFeeType":{"type":"string","enum":["assignment","shift","both"],"nullable":true},"requireVerifiedTimeDocumentation":{"type":"boolean","nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"documents":{"description":"pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each.","type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"isPrimaryAddress":{"description":"Make this the client's primary location.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Client location updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Location Updated!"},"data":{"properties":{"id":{"type":"integer","example":42}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Location Updated!","data":{"id":42}}}}},"401":{"description":"Unauthorized - Token required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The payload carries a Rates & Billing field (rates, single rates, admin fee, billing and cancellation terms) and the role has no Finance Edit, so nothing is saved. A payload without those fields follows the record's own permission alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A rate unit other than Per Hour or Per Minute (for example weekly) in a rate or single-rate row is refused and nothing is saved: the same 422 body with errors.unit, errors.assignmentRateUnit or errors.shiftRateUnit (no row index).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"The name field is required."}},"addressLine1":{"type":"array","items":{"type":"string","example":"The address line 1 field is required."}},"city":{"type":"array","items":{"type":"string","example":"The city field is required."}},"status.id":{"type":"array","items":{"type":"string","example":"The status.id field must be an integer."}},"contactEmail":{"type":"array","items":{"type":"string","example":"The contact email must be a valid email address."}},"rates.0.serviceType":{"type":"array","items":{"type":"string","example":"The selected service type is invalid."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation failed","errors":{"name":["The name field is required."],"addressLine1":["The address line 1 field is required."],"city":["The city field is required."],"status.id":["The status.id field must be an integer."],"contactEmail":["The contact email must be a valid email address."],"rates.0.serviceType":["The selected service type is invalid."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:edit","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/clients/{client}/locations/{location}/tab/{tab}":{"get":{"tags":["Clients"],"summary":"Retrieve specific tab details of a client location","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler\n\nFetches the details for a specific tab within a client location, based on the provided location ID and tab identifier.","operationId":"ext_get_clients_By_client_locations_By_location_tab_By_tab","parameters":[{"name":"client","in":"path","description":"Unique identifier of the client","required":true,"schema":{"type":"string","example":"CLT-VX6R0"}},{"name":"location","in":"path","description":"Unique identifier of the client location","required":true,"schema":{"type":"string","example":"CLTLOC-VX6R0"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'general', 'rates_billing', 'document_notes')","required":true,"schema":{"type":"string","enum":["general","rates_billing","document_notes"],"example":"general"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Client location details retrieved successfully","content":{"application/json":{"schema":{"description":"The payload follows the tab: general, rates_billing and document_notes each return their own object. An unrecognized tab still answers 200, with data null.","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Location details retrieved!"},"data":{"description":"One object for the requested tab. See the example for the general tab.","nullable":true,"oneOf":[{"type":"object"},{"type":"array","items":{"type":"object"}}]}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The rates_billing tab is Finances data, so a role without Finance Read is refused it whatever it holds on the record's own module. Every other tab follows the record's module alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified client location does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified client location does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/clients/{client}/tab/{tab}":{"get":{"tags":["Clients"],"summary":"Retrieve specific tab details of a client","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler\n\nFetches the details for a specific tab within a client, based on the provided client ID and tab identifier.","operationId":"ext_get_clients_By_client_tab_By_tab","parameters":[{"name":"client","in":"path","description":"Unique identifier of the client","required":true,"schema":{"type":"string","example":"CLT-ZGJ8T2"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'general', 'requirement_preferences', 'rates_billing', 'document_notes','associated_consumers','assignmentStats','historyLogs')","required":true,"schema":{"type":"string","enum":["general","requirement_preferences","rates_billing","document_notes","associated_consumers","localizations","assignmentStats","historyLogs"],"example":"general"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search the audit log. Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort column (default: created_at). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort direction (default: desc). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Rows per page (default: 10). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number (default: 1). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Client details retrieved successfully","content":{"application/json":{"schema":{"description":"The payload follows the tab: general, requirement_preferences, associated_consumers, rates_billing, document_notes, localizations and assignmentStats each return their own object. historyLogs answers with a paginated envelope instead — success, data and meta, and no message key. An unrecognized tab still answers 200, with data null.","properties":{"success":{"type":"boolean","example":true},"message":{"description":"Absent on the historyLogs tab.","type":"string","example":"Client details retrieved!"},"data":{"description":"One object for the requested tab, or an array of audit entries on historyLogs. See the example for the general tab.","nullable":true,"oneOf":[{"type":"object"},{"type":"array","items":{"type":"object"}}]},"meta":{"description":"Sent on the historyLogs tab only.","properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":24}},"type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The rates_billing tab is Finances data, so a role without Finance Read is refused it whatever it holds on the record's own module. Every other tab follows the record's module alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified client does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified client does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Clients","x-fido-area-rank":0}},"/v1/communication-modes":{"get":{"tags":["Settings · General"],"summary":"Retrieve all communication modes or filter by tenant ID","description":"**Required scope:** `settings_general:read`\n\nFetch a list of all communication modes or filter by a specific tenant ID if provided.","operationId":"ext_get_communication_modes","parameters":[{"name":"tenantId","in":"query","description":"Tenant ID for filtering.","required":false,"schema":{"type":"string","example":"demotenant"}}],"responses":{"200":{"description":"Communication modes retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication Modes Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Communication Modes Retrieved!","data":[{"id":1,"value":1,"label":"Example label","isCustom":true}]}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Communication modes","x-fido-area-rank":1},"post":{"tags":["Settings · General"],"summary":"Create a new communication mode","description":"**Required scope:** `settings_general:write`\n\nCreate a communication mode with a name and optional tenant ID.","operationId":"ext_post_communication_modes","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","tenant_id"],"properties":{"name":{"type":"string","example":"Phone Call"},"tenant_id":{"type":"string","example":"demotenant"}},"type":"object"}}}},"responses":{"201":{"description":"Communication mode created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication Mode created!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Communication Mode created!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Communication modes","x-fido-area-rank":1}},"/v1/communication-modes/{communication_mode}":{"delete":{"tags":["Settings · General"],"summary":"Delete a communication mode by id alone (always 422)","description":"**Required scope:** `settings_general:delete`\n\n**Use `/v1/communication-modes/{id}/{label}` instead.** This id-only form is registered by the resource route, but the handler identifies the record from a `label` path segment this route does not carry, so the call always fails validation with `label` required.","operationId":"ext_delete_communication_modes_By_communication_mode","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"communication_mode","in":"path","description":"ID of the communication mode.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed: the communication mode type could not be resolved from the URL.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The label field is required."}},"type":"object"},"example":{"status":"error","message":"The label field is required."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Communication modes","x-fido-area-rank":1},"get":{"tags":["Settings · General"],"summary":"Retrieve a single communication mode (not implemented)","description":"**Required scope:** `settings_general:read`\n\n**Not implemented.** The route is registered, but the controller action has no body, so the call succeeds with an empty response and no `{success, message, data}` envelope. Read the communication mode from the list endpoint `/v1/communication-modes` instead.","operationId":"ext_get_communication_modes_By_communication_mode","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"communication_mode","in":"path","description":"ID of the communication mode.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Empty body — the action is not implemented."},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Communication modes","x-fido-area-rank":1},"put":{"tags":["Settings · General"],"summary":"Update an existing communication mode","description":"**Required scope:** `settings_general:edit`\n\nUpdate a communication mode by ID.","operationId":"ext_put_communication_modes_By_communication_mode","parameters":[{"name":"communication_mode","in":"path","description":"ID of the communication mode to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Mode"}},"type":"object"}}}},"responses":{"200":{"description":"Communication mode updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication Mode updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Communication Mode updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Communication mode not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Communication mode with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Communication mode with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Communication modes","x-fido-area-rank":1},"patch":{"tags":["Settings · General"],"summary":"Update an existing communication mode","description":"**Required scope:** `settings_general:edit`\n\nUpdate a communication mode by ID.","operationId":"ext_patch_communication_modes_By_communication_mode","parameters":[{"name":"communication_mode","in":"path","description":"ID of the communication mode to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Mode"}},"type":"object"}}}},"responses":{"200":{"description":"Communication mode updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication Mode updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Communication Mode updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Communication mode not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Communication mode with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Communication mode with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Communication modes","x-fido-area-rank":1}},"/v1/communication-modes/{id}/{label}":{"delete":{"tags":["Settings · General"],"summary":"Delete a communication mode","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete a communication mode by its ID.","operationId":"ext_delete_communication_modes_By_id_By_label","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"ID of the communication mode to delete.","required":true,"schema":{"type":"integer","example":7}},{"name":"label","in":"path","description":"Label of the communication_mode to delete.","required":true,"schema":{"type":"string","example":"communication_mode"}}],"responses":{"200":{"description":"Communication mode deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication Mode deleted!"}},"type":"object"},"example":{"success":true,"message":"Communication Mode deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Communication mode not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Communication mode with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Communication mode with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Communication modes","x-fido-area-rank":1}},"/v1/consumer-types":{"get":{"tags":["Settings · General"],"summary":"Retrieve all consumer types or filter by tenant ID","description":"**Required scope:** `settings_general:read`\n\nFetch a list of predefined and custom consumer types, optionally filtered by tenant ID.","operationId":"ext_get_consumer_types","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"tenantId","in":"query","description":"Tenant ID for multi-tenant filtering.","required":false,"schema":{"type":"string","example":"demoTenant"}}],"responses":{"200":{"description":"Consumer Types retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer types Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Consumer types Retrieved!","data":[{"id":1,"value":1,"label":"Example label","isCustom":true}]}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Consumer types","x-fido-area-rank":2},"post":{"tags":["Settings · General"],"summary":"Create a new consumer type","description":"**Required scope:** `settings_general:write`\n\nCreate a new consumer type with a name and optional tenant ID.","operationId":"ext_post_consumer_types","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","tenant_id"],"properties":{"name":{"type":"string","example":"Autistic"},"tenant_id":{"type":"string","example":"demoTenant"}},"type":"object"}}}},"responses":{"201":{"description":"Consumer type created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer type created!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Consumer type created!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Consumer types","x-fido-area-rank":2}},"/v1/consumer-types/{consumer_type}":{"delete":{"tags":["Settings · General"],"summary":"Delete a consumer type by id alone (always 422)","description":"**Required scope:** `settings_general:delete`\n\n**Use `/v1/consumer-types/{id}/{label}` instead.** This id-only form is registered by the resource route, but the handler identifies the record from a `label` path segment this route does not carry, so the call always fails validation with `label` required.","operationId":"ext_delete_consumer_types_By_consumer_type","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"consumer_type","in":"path","description":"ID of the consumer type.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed: the consumer type type could not be resolved from the URL.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The label field is required."}},"type":"object"},"example":{"status":"error","message":"The label field is required."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Consumer types","x-fido-area-rank":2},"get":{"tags":["Settings · General"],"summary":"Retrieve a single consumer type (not implemented)","description":"**Required scope:** `settings_general:read`\n\n**Not implemented.** The route is registered, but the controller action has no body, so the call succeeds with an empty response and no `{success, message, data}` envelope. Read the consumer type from the list endpoint `/v1/consumer-types` instead.","operationId":"ext_get_consumer_types_By_consumer_type","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"consumer_type","in":"path","description":"ID of the consumer type.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Empty body — the action is not implemented."},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Consumer types","x-fido-area-rank":2},"put":{"tags":["Settings · General"],"summary":"Update an existing consumer type","description":"**Required scope:** `settings_general:edit`\n\nUpdate an existing consumer type by ID.","operationId":"ext_put_consumer_types_By_consumer_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"consumer_type","in":"path","description":"ID of the consumer type.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Consumer Type"}},"type":"object"}}}},"responses":{"200":{"description":"Consumer type updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer type updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Consumer type updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Consumer type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer type with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Consumer type with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Consumer types","x-fido-area-rank":2},"patch":{"tags":["Settings · General"],"summary":"Update an existing consumer type","description":"**Required scope:** `settings_general:edit`\n\nUpdate an existing consumer type by ID.","operationId":"ext_patch_consumer_types_By_consumer_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"consumer_type","in":"path","description":"ID of the consumer type.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Consumer Type"}},"type":"object"}}}},"responses":{"200":{"description":"Consumer type updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer type updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Consumer type updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Consumer type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer type with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Consumer type with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Consumer types","x-fido-area-rank":2}},"/v1/consumer-types/{id}/{label}":{"delete":{"tags":["Settings · General"],"summary":"Delete a consumer type","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete a consumer type by its ID.","operationId":"ext_delete_consumer_types_By_id_By_label","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"ID of the consumer type.","required":true,"schema":{"type":"integer","example":5}},{"name":"label","in":"path","description":"Label of the consumer_type to delete.","required":true,"schema":{"type":"string","example":"consumer_type"}}],"responses":{"200":{"description":"Consumer type deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer type deleted!"}},"type":"object"},"example":{"success":true,"message":"Consumer type deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Consumer type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer type with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Consumer type with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Consumer types","x-fido-area-rank":2}},"/v1/consumers/by-client":{"get":{"tags":["Consumers"],"summary":"Get consumers associated with a specific client","description":"**Required scope:** `consumers:read` or `clients:read` or `assignments:read` or `shifts:read` or `schedule:read` or `forms:read`\n\nFetches a list of consumers linked to a given client, only including those with is_published = true.","operationId":"ext_get_consumers_by_client","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-QLRJVTKH"}},{"name":"client","in":"query","description":"The ID of the client whose consumers should be fetched","required":true,"schema":{"type":"string","example":"CLT-UXVM8P"}},{"name":"isActive","in":"query","description":"When true, only includes consumers whose status is Active","required":false,"schema":{"type":"boolean","example":true}},{"name":"restrictedConsumers","in":"query","description":"When true, includes consumers this client has restricted; omitted or false excludes them (default)","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"List of Consumers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumers fetched successfully!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"John Doe"},"value":{"type":"string","example":"1"},"image":{"type":"string","example":"consumer_logo.png"}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Consumers fetched successfully!","data":[{"id":"1","label":"John Doe","value":"1","image":"consumer_logo.png"},{"id":"2","label":"Jane Smith","value":"2","image":null}]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read|clients:read|assignments:read|shifts:read|schedule:read|forms:read","x-fido-module":"consumers","x-fido-roles":[],"x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/consumers/document/files":{"delete":{"tags":["Consumers"],"summary":"Delete files associated with a consumer","description":"**Required scope:** `consumers:edit`  \n**Roles:** admin, client, scheduler\n\nDeletes uploaded files tied to a specific consumer.","operationId":"ext_delete_consumers_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["fileIds"],"properties":{"fileIds":{"description":"Array of consumer file IDs to delete","type":"array","items":{"type":"integer","example":8}}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully!"}},"type":"object"},"example":{"success":true,"message":"Files deleted successfully!"}}}},"400":{"description":"Bad request - Missing or invalid file ID(s)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid file ID(s) provided."}},"type":"object"},"example":{"success":false,"message":"Invalid file ID(s) provided."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:edit","x-fido-module":"consumers","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/consumers/export":{"get":{"tags":["Consumers"],"summary":"Export all Consumers to Excel","description":"**Required scope:** `consumers:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all consumers to an Excel file for download.","operationId":"ext_get_consumers_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-QLRJVTKH"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing all consumers","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/consumers/guardians/lookup":{"get":{"tags":["Consumers"],"summary":"Find an existing guardian by email","description":"**Required scope:** `consumers:read`  \n**Roles:** admin, scheduler\n\nReturns the guardian on file for the given email so a form can offer to link the existing person instead of creating a duplicate. Data is null when nobody matches.","operationId":"ext_get_consumers_guardians_lookup","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string"}},{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email"}}],"responses":{"200":{"description":"Lookup result (data is the guardian or null)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string"},"data":{"oneOf":[{"$ref":"#/components/schemas/GuardianLookup"}],"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/consumers/name-list":{"get":{"tags":["Consumers"],"summary":"Get all consumers' names and IDs","description":"**Required scope:** `consumers:read`  \n**Roles:** admin, scheduler\n\nFetches a list of all consumers with only their ID and name.","operationId":"ext_get_consumers_name_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-QLRJVTKH"}}],"responses":{"200":{"description":"List of Consumers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumers fetched successfully!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"John Doe"}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Consumers fetched successfully!","data":[{"id":1,"name":"John Doe"},{"id":2,"name":"Jane Smith"}]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/consumers/{consumer}":{"delete":{"tags":["Consumers"],"summary":"Delete a consumer","description":"**Required scope:** `consumers:delete`  \n**Roles:** admin, scheduler\n\nDeletes a specific consumer by ID. This will remove the consumer and all associated data such as configurations, preferences, documents, and user links.","operationId":"ext_delete_consumers_By_consumer","parameters":[{"name":"consumer","in":"path","description":"The ID of the consumer to delete.","required":true,"schema":{"type":"string","example":"CSM-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Consumer deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer deleted successfully!"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure the consumer ID exists."}},"type":"object"},"example":{"success":false,"message":"Invalid parameters. Ensure the consumer ID exists."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not Found - Consumer does not exist","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer not found."}},"type":"object"},"example":{"success":false,"message":"Consumer not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:delete","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Consumers","x-fido-area-rank":0},"post":{"tags":["Consumers"],"summary":"Update an existing consumer","operationId":"ext_post_consumers_By_consumer","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for the request","required":true,"schema":{"type":"string","example":"TNT-97MD3QAU"}},{"name":"consumer","in":"path","description":"Consumer ID (e.g., CSM-000123)","required":true,"schema":{"type":"string","example":"CSM-000123"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Same fields as create. Whether the published-only rules apply follows the isPublished sent, else the stored value.","required":["name","portalAccess"],"properties":{"name":{"type":"string","maxLength":255,"example":"Pat Doe"},"email":{"description":"Required when portalAccess, networkAccess or receiveEmail is true. Unique among this organization's users, and in the network when networkAccess is true.","type":"string","format":"email","maxLength":255,"example":"pat@example.test","nullable":true},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"dateOfBirth":{"description":"Under 18 makes the consumer a minor; a new minor needs a guardian or the independent-minor acknowledgment","type":"string","format":"date","example":"2014-05-01","nullable":true},"hasLegalGuardian":{"description":"Guardians act for this consumer whatever their age. Omit to leave as stored","type":"boolean","nullable":true},"independentMinorAck":{"description":"A minor deliberately with no guardian; needs independentMinorReason","type":"boolean","nullable":true},"independentMinorReason":{"type":"string","maxLength":255,"nullable":true},"notifyMinorToo":{"description":"Under guardianship, the consumer also receives their own notifications","type":"boolean","nullable":true},"guardians":{"description":"Replaces the consumer's guardian links when sent (a JSON string on multipart). Omit to leave them as they are","type":"array","items":{"$ref":"#/components/schemas/GuardianInput"},"nullable":true},"gender":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"phoneExtension":{"type":"string","maxLength":10,"example":"204","nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"addressLine1":{"type":"string","maxLength":255,"example":"101 Street","nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"type":"string","maxLength":100,"example":"Austin","nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"12345 or 12345-6789.","type":"string","example":"78759","nullable":true},"status":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"consumerType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"hearingStatus":{"description":"Required when published. id is a hearing-status value such as deaf.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"communicationModes":{"description":"Required when published.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"portalAccess":{"description":"Let the consumer sign in to the consumer portal. Defaults to the organization's auto-populate setting.","type":"boolean","example":false},"networkAccess":{"description":"Share the consumer with the Fido network.","type":"boolean","example":false,"nullable":true},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"enableCalendarIntegration":{"type":"boolean","nullable":true},"assignmentUpdates":{"description":"Notification preference.","type":"boolean","nullable":true},"serviceReminders":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"profileShareWithinOrganization":{"type":"boolean","nullable":true},"defaultTimezone":{"description":"Localization. Required when published.","type":"string","example":"America/Chicago","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization. Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization. Required when published.","type":"string","nullable":true},"startOfWeek":{"description":"Localization. Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startOfDay":{"description":"Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"Localization.","type":"string","example":"18:00","nullable":true},"preferredServiceLocations":{"description":"Required when published. id is onsite, remote or both.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"associatedClient":{"description":"Clients the consumer is associated with. Required when published. A client left out of an update is detached.","type":"array","items":{"properties":{"client":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"relationship":{"description":"Omit to keep the stored relationship; send null to clear it.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"allowPortalAccess":{"type":"boolean","nullable":true},"allowServiceRequests":{"type":"boolean","nullable":true},"allowAssignmentChanges":{"type":"boolean","nullable":true}},"type":"object"},"nullable":true},"userPreferred":{"description":"Preferred providers. Must not overlap userRestricted.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"description":"Restricted providers.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientRestricted":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"customizeRequirementPreferences":{"description":"Per-service-type requirements. true reads requirementAndPreferences; false reads the flat default-tier fields below.","type":"boolean","nullable":true},"serviceTypes":{"description":"Default requirement tier. Service types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderTypes":{"description":"Default requirement tier. Provider roles.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"providerTypes":{"description":"Default requirement tier. Provider types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"description":"Default requirement tier. Minimum skill level.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"genderPreferences":{"description":"Default requirement tier. Preferred provider gender.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"certifications":{"description":"Default requirement tier. Required certifications.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"clearances":{"description":"Default requirement tier. Required clearances.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"specializations":{"description":"Default requirement tier. Required specializations.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedClients":{"description":"Clients the consumer may not be scheduled with.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"description":"Consumer users restricted from this consumer.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"assignmentRequest":{"description":"Notification preference.","type":"boolean","nullable":true},"allowClientsToBroadcastImmediately":{"description":"The consumer's requests broadcast without scheduler review.","type":"boolean","nullable":true},"requirementAndPreferences":{"description":"Required with customizeRequirementPreferences=true when publishing a consumer that has no service type yet.","type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Changes to updated consumer were saved.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to updated consumer were saved."},"data":{"properties":{"id":{"type":"string","example":"CSM-000123"},"isDisableRole":{"description":"True when the roles payload turned the consumer role off for this person.","type":"boolean","example":false},"messages":{"description":"Status-change notices from the save — status updated, published or unpublished, activated or deactivated.","type":"array","items":{"type":"string"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Consumer not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer not found"}},"type":"object"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The given data was invalid."},"errors":{"properties":{"email":{"type":"array","items":{"type":"string","example":"The email field is required."}}},"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Consumer update failed: [error details]","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:edit","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `consumers:edit`  \n**Roles:** admin, scheduler","x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/consumers/{consumer}/tab/{tab}":{"get":{"tags":["Consumers"],"summary":"Retrieve specific tab details of a consumer","description":"**Required scope:** `consumers:read`  \n**Roles:** admin, scheduler\n\nFetches the details for a specific tab within a consumer, based on the provided consumer ID and tab identifier.","operationId":"ext_get_consumers_By_consumer_tab_By_tab","parameters":[{"name":"consumer","in":"path","description":"Unique identifier of the consumer","required":true,"schema":{"type":"string","example":"CSM-PMJKT2"}},{"name":"tab","in":"path","description":"The tab to fetch. `rates_billing` is accepted but has no consumer view, so it returns `data: null`.","required":true,"schema":{"type":"string","enum":["general","localizations","requirement_preferences","rates_billing","document_notes","associated_clients","assignmentStats"],"example":"general"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Consumer details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer details retrieved!"},"data":{"properties":{"id":{"type":"string","example":"CSM-PMJKT2"},"name":{"type":"string","example":"ABCD"},"description":{"type":"string","example":"Test description"},"email":{"type":"string","example":"user@example.com"},"logo":{"type":"string","nullable":true},"countryCode":{"type":"string","example":"+1"},"phone":{"type":"string","example":"9888888888"},"phoneType":{"type":"string","example":"sms_and_voice"},"videoPhoneCountryCode":{"type":"string","example":"+1"},"videoPhone":{"type":"string","example":"9888888888"},"addressLine1":{"type":"string","example":"101 Street"},"addressLine2":{"type":"string","example":"Beagle Run"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Texas"}},"type":"object"},"postalCode":{"type":"string","example":"78759"},"gender":{"properties":{"id":{"type":"string","example":"female"},"label":{"type":"string","example":"Female"}},"type":"object"},"dateOfBirth":{"type":"string","format":"date","example":"1990-04-12"},"portalAccess":{"type":"boolean","example":false},"inviteState":{"type":"string","example":"not_invited"},"inviteExpiresAt":{"type":"string","nullable":true},"enableCalendarIntegration":{"type":"boolean","example":false},"assignmentUpdates":{"type":"boolean","example":false},"serviceReminders":{"type":"boolean","example":false},"receiveEmail":{"type":"boolean","example":false},"receiveSms":{"type":"boolean","example":false},"receiveInApp":{"type":"boolean","example":false},"profileShareWithinOrganization":{"type":"boolean","example":false},"isPublished":{"type":"boolean","example":true},"networkAccess":{"type":"boolean","example":false},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"consumerType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Individual"}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL (American Sign Language)"}},"type":"object"}},"hearingStatus":{"properties":{"id":{"type":"string","example":"deaf"},"label":{"type":"string","example":"Deaf"}},"type":"object"},"customFields":{"type":"array","items":{"type":"object"}},"externalCustomFields":{"type":"array","items":{"type":"object"}},"roles":{"type":"array","items":{"type":"object"}}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Consumer details retrieved!","data":{"id":"CSM-PMJKT2","name":"ABCD","description":"Test description","email":"user@example.com","logo":null,"countryCode":"+1","phone":"9888888888","phoneType":"sms_and_voice","videoPhoneCountryCode":"+1","videoPhone":"9888888888","addressLine1":"101 Street","addressLine2":"Beagle Run","city":"Austin","state":{"id":1,"label":"Texas"},"postalCode":"78759","gender":{"id":"female","label":"Female"},"dateOfBirth":"1990-04-12","portalAccess":false,"inviteState":"not_invited","inviteExpiresAt":null,"enableCalendarIntegration":false,"assignmentUpdates":false,"serviceReminders":false,"receiveEmail":false,"receiveSms":false,"receiveInApp":false,"profileShareWithinOrganization":false,"isPublished":true,"networkAccess":false,"status":{"id":1,"label":"Active"},"priority":{"id":1,"label":"High"},"consumerType":{"id":1,"label":"Individual"},"communicationModes":[{"id":1,"label":"ASL (American Sign Language)"}],"hearingStatus":{"id":"deaf","label":"Deaf"},"customFields":[],"externalCustomFields":[],"roles":[]}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified consumer does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified consumer does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/dashboard/client-portal/distribution":{"get":{"tags":["Clients"],"summary":"Get client portal dashboard distribution","description":"**Required scope:** `clients:read`  \n**Roles:** client\n\nRetrieve distribution dashboard data for client portal (consumers and locations)","operationId":"ext_get_dashboard_client_portal_distribution","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}}],"responses":{"200":{"description":"Dashboard distribution retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Dashboard distribution retrieved successfully"},"data":{"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Client portal dashboard","x-fido-area-rank":4}},"/v1/dashboard/client-portal/overview":{"get":{"tags":["Clients"],"summary":"Get client portal dashboard overview","description":"**Required scope:** `clients:read`  \n**Roles:** client\n\nRetrieve overview dashboard data for client portal","operationId":"ext_get_dashboard_client_portal_overview","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"type","in":"query","description":"Which stats to return. 'assignment' (default) returns assignment/shift stats; 'request' returns request stats instead (only when the org's 'allow client create request' setting is enabled — otherwise returns empty stats).","required":false,"schema":{"type":"string","enum":["assignment","request"],"example":"assignment"}}],"responses":{"200":{"description":"Dashboard overview retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Dashboard overview retrieved successfully"},"data":{"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Client portal dashboard","x-fido-area-rank":4}},"/v1/dashboard/consumer-portal/stats":{"get":{"tags":["Consumers"],"summary":"Get consumer portal dashboard statistics","description":"**Required scope:** `consumers:read`  \n**Roles:** consumer\n\nRetrieve dashboard statistics for consumer portal (assignments and requests)","operationId":"ext_get_dashboard_consumer_portal_stats","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}}],"responses":{"200":{"description":"Consumer dashboard statistics retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer dashboard statistics retrieved successfully"},"data":{"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/dashboard/provider-portal/assignment-confirm/{id}/{assignmentId}":{"put":{"tags":["Providers"],"summary":"Confirm an assignment for a service provider","description":"**Required scope:** `providers:edit`  \n**Roles:** service-provider\n\nConfirms an assignment for a service provider based on assignment ID and slot ID.","operationId":"ext_put_dashboard_provider_portal_assignment_confirm_By_id_By_assignmentId","parameters":[{"name":"id","in":"path","description":"ID","required":true,"schema":{"type":"integer","example":162}},{"name":"assignmentId","in":"path","description":"Assignment or Shift ID (as per system design)","required":true,"schema":{"type":"string","example":"ASG-X9C9WG"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}}],"responses":{"200":{"description":"Assignment confirmed successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment confirmed successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment not found"},"data":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:edit","x-fido-module":"providers","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/dashboard/provider-portal/assignment-confirmation-popup/{tab}":{"get":{"tags":["Providers"],"summary":"Get assignment or shift confirmation popup details","description":"**Required scope:** `providers:read`  \n**Roles:** service-provider\n\nReturns the next assignment or shift requiring service provider confirmation, including time until start and service type.","operationId":"ext_get_dashboard_provider_portal_assignment_confirmation_popup_By_tab","parameters":[{"name":"tab","in":"path","description":"Tab from which the popup is requested (dashboard | schedule)","required":true,"schema":{"type":"string","example":"dashboard"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}}],"responses":{"200":{"description":"Assignment or shift details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment details retrieved successfully"},"data":{"properties":{"type":{"type":"string","example":"shift"},"assignmentId":{"type":"string","example":"SFT-PJ1X3C"},"title":{"type":"string","example":"Shift"},"id":{"type":"integer","example":1},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"startTime":{"type":"string","example":"Nov 14, 2025 08:30 AM"},"timeUntilStart":{"type":"string","example":"10 minutes"},"pendingCount":{"description":"Jobs starting later today that still need this provider's confirmation, the one shown included","type":"integer","example":1},"message":{"type":"string","example":"10 minutes until assignment starts\\nASL interpretation for Assignment (ID: SFT-PJ1X3C)\\n👉 Please confirm your availability before it begins."}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"No upcoming assignments found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"No upcoming assignments found"},"data":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/dashboard/provider-portal/service-impact":{"get":{"tags":["Providers"],"summary":"Get service provider impact statistics","description":"**Required scope:** `providers:read`  \n**Roles:** service-provider\n\nRetrieve service impact statistics including consumers supported, clients supported, and locations worked","operationId":"ext_get_dashboard_provider_portal_service_impact","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}}],"responses":{"200":{"description":"Service impact statistics retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service impact statistics retrieved successfully"},"data":{"properties":{"cards":{"type":"array","items":{"properties":{"key":{"type":"string","example":"consumers_supported"},"title":{"type":"string","example":"Consumers Supported"},"total":{"type":"integer","example":24},"breakdown":{"type":"array","items":{"properties":{"label":{"type":"string","example":"On-Site"},"value":{"type":"integer","example":18},"type":{"type":"string","example":"onsite"}},"type":"object"}}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/dashboard/provider-portal/stats":{"get":{"tags":["Providers"],"summary":"Get service provider portal dashboard statistics","description":"**Required scope:** `providers:read`  \n**Roles:** service-provider\n\nRetrieve dashboard statistics for service provider portal","operationId":"ext_get_dashboard_provider_portal_stats","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}}],"responses":{"200":{"description":"Provider dashboard statistics retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider dashboard statistics retrieved successfully"},"data":{"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/ethnicities":{"get":{"tags":["Settings · General"],"summary":"Retrieve paginated ethnicities with optional filters","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of ethnicities. Allows search and sorting. Supports multi-tenancy via X-TENANT-ID header. `isCustom` is false for the default entries, which can't be renamed or deleted.","operationId":"ext_get_ethnicities","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"Asian"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortBy","in":"query","description":"Field to sort by (defaults to id)","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc, defaults to desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Ethnicities retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Asian"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":9}},"type":"object"}},"type":"object"}}}},"400":{"description":"The list could not be read.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve.","errors":null,"code":""}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Ethnicities","x-fido-area-rank":5},"post":{"tags":["Settings · General"],"summary":"Create one or more ethnicities","description":"**Required scope:** `settings_general:write`  \n**Roles:** admin, scheduler\n\nAdd custom ethnicities to the organization's list. Entries added here are custom (`isCustom` true) and can be renamed or deleted.","operationId":"ext_post_ethnicities","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"description":"One or more entries to add. Multipart requests may send it as a JSON string.","type":"array","items":{"required":["label"],"properties":{"label":{"type":"string","maxLength":255,"example":"Caribbean"}},"type":"object"}}},"type":"object"}}}},"responses":{"201":{"description":"Ethnicity created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Custom ethnicity Caribbean (10) has been saved successfully."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed (missing name, a name already on the list in any case, or the same name given twice in one request).","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn't save this ethnicity. Correct the highlighted fields and try again."},"errors":{"description":"Messages keyed by the field they belong to; every entry's message lands on `name`.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"},"example":{"status":"error","message":"We couldn't save this ethnicity. Correct the highlighted fields and try again.","errors":{"name":["This ethnicity already exists."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Ethnicities","x-fido-area-rank":5}},"/v1/ethnicities/{ethnicity}":{"delete":{"tags":["Settings · General"],"summary":"Delete a custom ethnicity","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nArchive a custom ethnicity by ID. Default entries (`isCustom` false) can't be deleted.","operationId":"ext_delete_ethnicities_By_ethnicity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"ethnicity","in":"path","description":"ID of the ethnicity to delete.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Ethnicity deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Custom ethnicity Caribbean (10) was deleted successfully."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"400":{"description":"The entry is a default, or archived.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Default ethnicities can't be deleted."},"errors":{"type":"string","example":"Failed to delete."},"code":{"type":"string","example":""}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"An unknown id.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields","errors":{"id":["Ethnicity not found."]},"code":""}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Ethnicities","x-fido-area-rank":5},"get":{"tags":["Settings · General"],"summary":"Retrieve an ethnicity by ID","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch an ethnicity by its ID.","operationId":"ext_get_ethnicities_By_ethnicity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"ethnicity","in":"path","description":"ID of the ethnicity to retrieve.","required":true,"schema":{"type":"integer","example":3}}],"responses":{"200":{"description":"Ethnicity retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Ethnicity retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":3},"value":{"type":"integer","example":3},"label":{"type":"string","example":"Asian"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"400":{"description":"No active entry with that id.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Ethnicity not found."},"errors":{"type":"string","example":"Failed to retrieve."},"code":{"type":"string","example":""}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The id is not a number (the route only matches numeric ids).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The route api/v1/ethnicities/abc could not be found."},"errors":{"type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Ethnicities","x-fido-area-rank":5},"put":{"tags":["Settings · General"],"summary":"Rename a custom ethnicity","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nRename a custom ethnicity by ID. Default entries (`isCustom` false) can't be renamed.","operationId":"ext_put_ethnicities_By_ethnicity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"ethnicity","in":"path","description":"ID of the ethnicity to update.","required":true,"schema":{"type":"integer","example":10}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Afro-Caribbean"}},"type":"object"}}}},"responses":{"200":{"description":"Ethnicity updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to custom ethnicity Afro-Caribbean (10) were saved."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"An unknown id, or a missing or taken name (the form shape, with `status`); or an archived entry or a default (the envelope, with `success`).","content":{"application/json":{"schema":{"oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn't save this ethnicity. Correct the highlighted fields and try again."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"type":"object","additionalProperties":{"type":"string"}},"code":{"type":"string","example":""}},"type":"object"}]},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields","errors":{"name":"Default ethnicities can't be renamed."},"code":""}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Ethnicities","x-fido-area-rank":5},"patch":{"tags":["Settings · General"],"summary":"Rename a custom ethnicity","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nRename a custom ethnicity by ID. Default entries (`isCustom` false) can't be renamed.","operationId":"ext_patch_ethnicities_By_ethnicity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"ethnicity","in":"path","description":"ID of the ethnicity to update.","required":true,"schema":{"type":"integer","example":10}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Afro-Caribbean"}},"type":"object"}}}},"responses":{"200":{"description":"Ethnicity updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to custom ethnicity Afro-Caribbean (10) were saved."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"An unknown id, or a missing or taken name (the form shape, with `status`); or an archived entry or a default (the envelope, with `success`).","content":{"application/json":{"schema":{"oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn't save this ethnicity. Correct the highlighted fields and try again."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"type":"object","additionalProperties":{"type":"string"}},"code":{"type":"string","example":""}},"type":"object"}]},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields","errors":{"name":"Default ethnicities can't be renamed."},"code":""}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Ethnicities","x-fido-area-rank":5}},"/v1/export-client/{client}":{"get":{"tags":["Clients"],"summary":"Export a Client to Excel","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports single client to an Excel file for download.","operationId":"ext_get_export_client_By_client","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"client","in":"path","description":"Unique identifier of the client to export.","required":true,"schema":{"type":"string","example":"CLT-4GVGJ"}}],"responses":{"200":{"description":"Excel file containing client","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Clients","x-fido-area-rank":0}},"/v1/export-consumer/{consumer}":{"get":{"tags":["Consumers"],"summary":"Export a Consumer to Excel","description":"**Required scope:** `consumers:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports a single consumer to an Excel file for download.","operationId":"ext_get_export_consumer_By_consumer","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-QLRJVTKH"}},{"name":"consumer","in":"path","description":"Unique identifier of the consumer to export.","required":true,"schema":{"type":"string","example":"CSM-SZ45GS"}}],"responses":{"200":{"description":"Excel file containing the exported consumer","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Consumer not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer not found with the provided ID."}},"type":"object"},"example":{"success":false,"message":"Consumer not found with the provided ID."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Consumers","x-fido-area-rank":0}},"/v1/export-location/{id}":{"get":{"tags":["Settings · Organization Locations"],"summary":"Export organization Location to Excel","description":"**Required scope:** `settings_locations:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports single organization Location to an Excel file for download.","operationId":"ext_get_export_location_By_id","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"path","description":"Unique identifier of the organization location","required":true,"schema":{"type":"string","example":"ORGLOC-4GVGJ"}}],"responses":{"200":{"description":"Excel file containing organization Location","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:read","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/export-scheduler/{scheduler}":{"get":{"tags":["Team"],"summary":"Export a single scheduler to Excel","description":"**Required scope:** `team:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports one scheduler's profile as an XLSX download.","operationId":"ext_get_export_scheduler_By_scheduler","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"scheduler","in":"path","description":"Scheduler ID","required":true,"schema":{"type":"string","example":"USR-CGQZDP"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"XLSX file download","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Scheduler not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The specified scheduler could not be found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:read","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Schedulers","x-fido-area-rank":0}},"/v1/finance/acknowledge":{"post":{"tags":["Finances"],"summary":"Acknowledge receipt or payment on a portal finance document","description":"**Required scope:** `finance:write`\n\nPortal-only (client/provider). kind=receipt for invoice/pro_forma; kind=payment for payable. Idempotent: already-acknowledged returns 200 with existing fields. Wrong owner returns 404; admin/scheduler returns 403.","operationId":"ext_post_finance_acknowledge","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["type","document_id","kind"],"properties":{"type":{"type":"string","enum":["invoice","pro_forma","payable"],"example":"invoice"},"document_id":{"type":"string","example":"INV-001"},"kind":{"type":"string","enum":["receipt","payment"],"example":"receipt"}},"type":"object"}}}},"responses":{"200":{"description":"Acknowledged (or already acknowledged)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Receipt acknowledged."},"data":{"properties":{"already_acknowledged":{"type":"boolean","example":false},"acknowledged_at":{"type":"string","format":"date-time","example":"2026-01-15 09:00:00"},"acknowledged_by":{"type":"string","example":"USR-1"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Non-portal role","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not found or not owned","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"Not eligible","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":[],"x-fido-area":"Documents","x-fido-area-rank":6}},"/v1/finance/calculate-preview":{"post":{"tags":["Finances"],"summary":"Calculate finance preview","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nCalculates and previews finance totals (invoices, pro-forma, payables, payment statements) including work item charges without creating the document. Applies the same paid-source zeroing as save (excludes billable entities already on a paid document for the same client/provider, or paid selected invoices/payables; duplicate-from-paid via source_document_id). Pass full_copy=true after reverse-and-cancel reissue to keep full charges (skips paid-source zeroing). When type is invoice and billable_entities include client-billed assignments or shifts, client_id is required; omit client_id for organization-billed-only previews (or set is_org_invoice=true). When type is payable and billable_entities include assignments or shifts, provider_id is required.","operationId":"ext_post_finance_calculate_preview","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["type"],"properties":{"current_document_id":{"description":"The document being edited, so its own lines are not counted twice against the work items it already bills.","type":"string","example":"INV-EWDM3W","nullable":true},"type":{"description":"Finance document type","type":"string","enum":["invoice","proforma","payable","payment_statement"],"example":"invoice"},"source_document_id":{"description":"Optional source document ID for duplication context. When the source is paid, preview zeroes amounts the same way as save.","type":"string","example":"INV-ABC123"},"full_copy":{"description":"When true (reverse-and-cancel reissue), skip paid-source zeroing so preview keeps full charges. Default false.","type":"boolean","example":true},"line_items":{"description":"Array of line items","type":"array","items":{"required":["amount","name","description","type"],"properties":{"amount":{"description":"Line item amount","type":"number","format":"float","example":150},"name":{"description":"Line item name","type":"string","example":"Consultation Fee"},"description":{"description":"Line item description","type":"string","example":"Initial consultation service"},"type":{"description":"Line item type","properties":{"id":{"description":"Line item type ID","type":"string","example":"charges"},"label":{"description":"Line item type label","type":"string","example":"Additional Charge"}},"type":"object"}},"type":"object"}},"tax_type":{"description":"Tax type","properties":{"id":{"description":"Tax type ID","type":"string","example":"Percentage"},"label":{"description":"Tax type label","type":"string","example":"Percentage"}},"type":"object"},"tax_amount":{"description":"Tax amount","type":"number","format":"float","example":15},"discount_type":{"description":"Discount type","properties":{"id":{"description":"Discount type ID","type":"string","example":"Fixed"},"label":{"description":"Discount type label","type":"string","example":"Fixed"}},"type":"object"},"discount_amount":{"description":"Discount amount","type":"number","format":"float","example":10},"billable_entities":{"description":"Billable entities. For type=payable use linkage rows only; pay fields go in billable_entities_pay_calc.","type":"array","items":{"oneOf":[{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"}},"type":"object"},{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift","invoice","payable"],"example":"assignment"},"id":{"type":"string","example":"ASG-DY1R0A-C3"}},"type":"object"}]}},"billable_entities_pay_calc":{"description":"Required for type=payable when billable_entities includes assignments/shifts.","type":"array","items":{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"type":"string","enum":["scheduled_time","actual_worked_time","scheduled_actual_fallback"],"nullable":true},"hours_used_for_pay":{"type":"number","format":"float","example":4,"nullable":true},"pay_rate":{"type":"number","format":"float","example":65,"nullable":true},"services_charge":{"type":"number","format":"float","example":260,"nullable":true},"hours_override_reason":{"type":"string","minLength":3,"nullable":true},"pay_rate_override_reason":{"type":"string","minLength":3,"nullable":true}},"type":"object"}},"billable_entities_billing":{"description":"Per work-item billing intent. billing_mode=bill enforces conflict checks on save; reference bypasses conflicts and zeros service charges on preview.","type":"array","items":{"required":["id"],"properties":{"id":{"type":"string","example":"ASG-OYLEV4"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill"},"bill_service":{"type":"boolean","example":true},"bill_expenses":{"type":"boolean","example":true},"bill_admin_fee":{"type":"boolean","example":true},"adminFeeBreakdown":{"description":"Optional per-entity admin fee override. Omit or send feeSource=calculated with empty clients/providers to derive from live config.","properties":{"feeSource":{"type":"string","enum":["calculated","manual"]},"clients":{"type":"array","items":{"type":"object"}},"providers":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true}},"type":"object"}},"is_org_invoice":{"description":"Optional. Explicit organization summary invoice preview. When all billable work items are organization-billed, client_id may be omitted even without this flag.","type":"boolean","example":true},"client_id":{"description":"Required when type=invoice and billable_entities contain client-billed assignments or shifts. Omit for organization-billed-only previews.","properties":{"id":{"description":"Client user ID","type":"string","example":"USR-12345"},"label":{"description":"Client display label","type":"string","example":"Acme Corp"}},"type":"object"},"provider_id":{"description":"Required when type=payable and billable_entities contain assignment or shift.","properties":{"id":{"description":"Provider user ID","type":"string","example":"SPR-67890"},"label":{"description":"Provider display label","type":"string","example":"Jane Provider"}},"type":"object"},"payable_id":{"description":"Optional for type=payable when editing; loads the stored admin fee snapshots and excludes this payable from billing_conflicts.","type":"string","example":"PAYB-ABC123","nullable":true},"invoice_id":{"description":"Optional for type=invoice when editing; alias for id. Excludes this invoice from billing_conflicts.","type":"string","example":"INV-ABC123","nullable":true},"id":{"description":"Optional document id when editing an existing invoice or payable. Excludes this document from billing_conflicts; when Canceled/Void, billing_conflicts is empty.","type":"string","example":"INV-ABC123","nullable":true},"has_changes":{"description":"Edit only. false or omitted on the first preview of an existing document: updatedAt is its stored update time. true after the user changes the form: updatedAt is the current time. Ignored on add, where updatedAt is always the current time.","type":"boolean","example":false},"payments_applied":{"description":"Optional. Payments applied (used for pro-forma / payment statement).","type":"number","format":"float","example":0}},"type":"object"}}}},"responses":{"200":{"description":"Finance preview calculated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Finance preview calculated successfully."},"data":{"properties":{"subtotal":{"description":"Finance subtotal","type":"number","format":"float","example":250},"services_charges":{"description":"Service-only charges. For type=payable, sum of per-entity service amounts (breakdown cost or hours×rate override per billable_entities[] item).","type":"number","format":"float","example":200},"original_services_charges":{"description":"Invoice preview comparison field. Sum of non-cancellation service charges across selected entities.","type":"number","format":"float","example":220,"nullable":true},"cancellation_services_charges":{"description":"Invoice preview comparison field. Sum of cancellation fees across selected entities.","type":"number","format":"float","example":140,"nullable":true},"original_payable_services_charges":{"description":"Payable preview comparison field. Sum using estimated pay basis.","type":"number","format":"float","example":160,"nullable":true},"cancellation_payable_services_charges":{"description":"Payable preview comparison field. Sum using cancellation pay basis.","type":"number","format":"float","example":100,"nullable":true},"expenses_total":{"description":"Expense-only total (invoice/payable contexts)","type":"number","format":"float","example":35},"total_admin_fee":{"description":"Combined admin fee total (invoice/proforma context)","type":"number","format":"float","example":20},"organization_admin_fee":{"description":"Sum of organization/scheduler admin fee across selected billable entities (invoice/proforma preview).","type":"number","format":"float","example":12},"provider_admin_fee":{"description":"Sum of service provider admin fee across selected billable entities (invoice/proforma preview).","type":"number","format":"float","example":8},"billable_entities_billing":{"description":"Invoice/payable only. Per work-item billing intent with resolved adminFeeBreakdown.","type":"array","items":{"type":"object"}},"tax_amount":{"description":"Tax amount","type":"number","format":"float","example":25},"discount_amount":{"description":"Adjustment amount","type":"number","format":"float","example":12.5},"total":{"description":"Total amount","type":"number","format":"float","example":287.5},"balance_due":{"description":"Balance due","type":"number","format":"float","example":257.5},"total_entities_count":{"description":"Number of billable entities in the request","type":"integer","example":2},"total_after_cancellation":{"description":"Invoice preview total when cancellation basis is applied.","type":"number","format":"float","example":182,"nullable":true},"balance_due_after_cancellation":{"description":"Invoice preview balance due when cancellation basis is applied.","type":"number","format":"float","example":182,"nullable":true},"original_balance_due":{"description":"Invoice preview balance due using original non-cancellation service basis.","type":"number","format":"float","example":232,"nullable":true},"total_payable_after_cancellation":{"description":"Payable preview total when cancellation pay basis is applied.","type":"number","format":"float","example":120,"nullable":true},"payable_balance_due_after_cancellation":{"description":"Payable preview balance due when cancellation pay basis is applied.","type":"number","format":"float","example":120,"nullable":true},"original_payable_balance_due":{"description":"Payable preview balance due using estimated pay basis.","type":"number","format":"float","example":170,"nullable":true},"work_item_service_breakdown":{"description":"Flattened service breakdown rows for selected entities. Each row includes `charge_source` (`service_charge|cancellation_fee` for invoice, `estimated_pay|cancellation_pay` for payable). Rows always describe the service as scheduled (`cost` = rate × billable duration), including for canceled work items; read `billable_amount` for the figure actually billed.","type":"array","items":{"properties":{"label":{"type":"string","example":"Standard Rate"},"hours":{"type":"number","format":"float","example":4},"rate":{"type":"number","format":"float","example":25},"cost":{"description":"Scheduled service math (rate × billable duration). Unchanged by cancellation.","type":"number","format":"float","example":100},"billable_amount":{"description":"What this row actually bills. Equals `cost` normally; on a canceled row it is that row's share of the cancellation fee (0 when the client is not billed for cancellation). Sums to `services_charges`.","type":"number","format":"float","example":25},"cancellation_fee":{"description":"This row's share of the client cancellation fee.","type":"number","format":"float","example":25},"original_cost":{"type":"number","format":"float","example":100},"charge_source":{"type":"string","example":"cancellation_fee"},"rate_source":{"description":"Payable rows only. Which rate configuration the row's pay rate came from.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"},"nullable":true},"entity_pay_metrics":{"description":"Payable only. Per-assignment/shift pay calculation metrics.","type":"array","items":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"type":"string","example":"scheduled_actual_fallback"},"derived_hours_used_for_pay":{"type":"number","format":"float","example":8},"hours_used_for_pay":{"type":"number","format":"float","example":8},"is_hours_overridden":{"type":"boolean","example":false},"derived_pay_rate":{"type":"number","format":"float","example":45},"pay_rate":{"type":"number","format":"float","example":45},"is_pay_rate_overridden":{"type":"boolean","example":false},"services_charge":{"type":"number","format":"float","example":260},"pay_rate_breakdown":{"properties":{"base_rate":{"type":"number","format":"float","example":45},"base_hours":{"type":"number","format":"float","example":8},"rules_applied":{"type":"array","items":{"type":"object"}},"rate_lines":{"type":"array","items":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}},"summary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"effective_pay_rate":{"type":"number","format":"float","example":46.67},"total_service_charge":{"type":"number","format":"float","example":360},"source":{"description":"Which time basis priced the lines — not where the rate came from; see rate_source.","type":"string","enum":["check_in","estimated_pay"]},"rate_source":{"description":"Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"description":"Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.","type":"string","example":"Provider Pay Rate","nullable":true},"rate_source_description":{"type":"string","example":"Driven by this provider's own custom pay rate configuration.","nullable":true},"rate_source_is_mixed":{"description":"True when the lines were priced from more than one rate configuration.","type":"boolean","example":false},"rate_configuration":{"description":"Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows.","properties":{"source":{"description":"Null when the work item was priced from more than one configuration.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"label":{"type":"string","example":"Default Pay Rate","nullable":true},"description":{"type":"string","example":"Driven by the organization default provider pay rate configuration.","nullable":true},"is_mixed":{"type":"boolean","example":false},"rows":{"type":"array","items":{"properties":{"service_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"service_provider_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"rate_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"site_type":{"type":"string","example":"onsite_client","nullable":true},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","enum":["hr","min"],"example":"hr"},"source":{"type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"rate_rules_suppressed":{"type":"boolean","example":false},"warning_message":{"type":"string","nullable":true},"hours_override_reason":{"type":"string","nullable":true},"pay_rate_override_reason":{"type":"string","nullable":true}},"type":"object"},"nullable":true},"billing_conflicts":{"description":"Soft conflicts when billable_entities_billing marks an entity as bill but it is already on another active document.","type":"array","items":{"properties":{"work_item_id":{"type":"string","example":"ASG-OYLEV4"},"document_id":{"type":"string","example":"INV-TOHWMO"},"document_type":{"type":"string","example":"invoice"},"message":{"type":"string","example":"ASG-OYLEV4 is already billed on Invoice INV-TOHWMO. Remove it or mark it as reference only."}},"type":"object"}},"updatedAt":{"description":"On add, the current time. On the first preview of an existing document (has_changes false or omitted), its stored update time. After the user changes the form (has_changes true), the current time. In the organization's date and time format.","type":"string","example":"07/31/2026 06:22 PM"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"type":["Type is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Finance preview failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/clients/{clientId}/assignments-shifts":{"get":{"tags":["Finances"],"summary":"Get assignments and shifts for a client","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves published (non-deleted) assignments and shifts linked to a client for manual invoice/payable creation. Includes all statuses; drafts and soft-deleted work items are excluded. Soft eligibility hints (invoice_eligible, client_is_no_show, stored_no_show_fee) are advisory — charge engine / 422 validation remain authoritative.","operationId":"ext_get_finance_clients_By_clientId_assignments_shifts","parameters":[{"name":"clientId","in":"path","description":"Client ID to get assignments and shifts for","required":true,"schema":{"type":"string","example":"CLT-XZQLQ1"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"document_id","in":"query","description":"Optional invoice id (INV-…) already being edited/duplicated. Linked work items are returned even if soft-deleted or unpublished, with the same shape as create (including name). Must belong to this client.","required":false,"schema":{"type":"string","example":"INV-ABC123"}}],"responses":{"200":{"description":"Assignments and shifts retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignments and shifts retrieved successfully"},"data":{"type":"array","items":{"properties":{"type":{"description":"Type of work","type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"description":"Unique identifier","type":"string","example":"ASG-12345"},"name":{"description":"Display name","type":"string","example":"Assignment Title"},"status":{"description":"Current status","type":"string","example":"Completed"},"status_slug":{"description":"Status slug","type":"string","example":"completed"},"finance_bucket":{"description":"Finance money bucket for document mixing rules","type":"string","enum":["standard","canceled","no-show"],"example":"standard"},"client_is_no_show":{"description":"Client picker: whether this client is marked no-show on the work item","type":"boolean","example":false},"stored_no_show_fee":{"description":"Client picker: stored no-show fee for this client when marked","type":"number","format":"float","example":25,"nullable":true},"invoice_eligible":{"description":"Soft hint only: false for provider-only no-show work items; not a substitute for save-time 422 / charge engine","type":"boolean","example":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Client not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Client not found"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/clients/{clientId}/credit-wallet":{"get":{"tags":["Finances"],"summary":"Get client credit wallet balance and ledger entries","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nT23 — Returns client-level unapplied credit wallet balance and ledger rows. Entries may include soft earmark metadata (`from_invoice:{id}`) from Reverse & Cancel apply_to_new_invoice; earmark is UX-only (`soft_lock=false`) and does not hard-lock spend. Wallet balance is readable; applying credit to an invoice (spend API) is not shipped yet (T22 deferred).","operationId":"ext_get_finance_clients_By_clientId_credit_wallet","parameters":[{"name":"clientId","in":"path","description":"Client ID","required":true,"schema":{"type":"string","example":"CLT-XZQLQ1"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Client credit wallet retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client credit wallet retrieved successfully"},"data":{"properties":{"balance":{"type":"number","format":"float","example":120},"entries":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"amount":{"type":"number","format":"float","example":120},"entry_type":{"type":"string","example":"rc_fold_credit"},"tag":{"type":"string","example":"from_invoice:INV-ABC123"},"earmark":{"properties":{"source_invoice_id":{"type":"string","example":"INV-ABC123"},"soft_lock":{"type":"boolean","example":false}},"type":"object","nullable":true}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/download":{"post":{"tags":["Finances"],"summary":"Download finance document PDF","description":"**Required scope:** `finance:read`\n\nGenerates and downloads a PDF version of the specified finance document (invoice, pro-forma, payable, or payment statement). Works for all finance document types.","operationId":"ext_post_finance_download","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["type","document_id"],"properties":{"type":{"description":"Finance document type","type":"string","enum":["invoice","pro_forma","payable","payment_statement"],"example":"invoice"},"document_id":{"description":"Document ID to download","type":"string","example":"INV-001"}},"type":"object"}}}},"responses":{"200":{"description":"Document PDF downloaded successfully","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The specified invoice does not exist."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"type":["Document type is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Document download failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":[],"x-fido-area":"Documents","x-fido-area-rank":6}},"/v1/finance/export/invoices":{"get":{"tags":["Finances"],"summary":"Export invoices","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports invoice data to a CSV file with optional filtering by specific invoice IDs.","operationId":"ext_get_finance_export_invoices","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"ids","in":"query","description":"Comma-separated list of invoice IDs to export. If not provided, exports all invoices.","required":false,"schema":{"type":"string","example":"INV-001,INV-002,INV-003"}},{"name":"format","in":"query","description":"`relational` returns a multi-sheet workbook with the line items on their own sheets; anything else returns the flat one-row-per-document sheet. A relational export is always XLSX, even with type=csv.","required":false,"schema":{"type":"string","default":"flat","enum":["flat","relational"]}}],"responses":{"200":{"description":"Up to the async threshold (config exports.async_threshold, default 100 rows) the file downloads directly. Above it the export is queued and a JSON notice comes back instead; the file is delivered by in-app and email notification.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"properties":{"queued":{"type":"boolean","example":true},"export_id":{"type":"string","example":"9d3c1f8e-2b7a-4c55-9a1e-3f6d2b8c7e10"},"message":{"type":"string","example":"Exporting 1,250 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The caller's role may not export invoices.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Export failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/export/payables":{"get":{"tags":["Finances"],"summary":"Export payables","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports payable data to a CSV file with optional filtering by specific payable IDs.","operationId":"ext_get_finance_export_payables","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"ids","in":"query","description":"Comma-separated list of payable IDs to export. If not provided, exports all payables.","required":false,"schema":{"type":"string","example":"PAY-001,PAY-002,PAY-003"}},{"name":"format","in":"query","description":"`relational` returns a multi-sheet workbook with the line items on their own sheets; anything else returns the flat one-row-per-document sheet. A relational export is always XLSX, even with type=csv.","required":false,"schema":{"type":"string","default":"flat","enum":["flat","relational"]}}],"responses":{"200":{"description":"Up to the async threshold (config exports.async_threshold, default 100 rows) the file downloads directly. Above it the export is queued and a JSON notice comes back instead; the file is delivered by in-app and email notification.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"properties":{"queued":{"type":"boolean","example":true},"export_id":{"type":"string","example":"9d3c1f8e-2b7a-4c55-9a1e-3f6d2b8c7e10"},"message":{"type":"string","example":"Exporting 1,250 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The caller's role may not export payables.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Export failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/export/payment-statements":{"get":{"tags":["Finances"],"summary":"Export payment statements","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports payment statement data to a CSV file with optional filtering by specific payment statement IDs.","operationId":"ext_get_finance_export_payment_statements","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"ids","in":"query","description":"Comma-separated list of payment statement IDs to export. If not provided, exports all payment statements.","required":false,"schema":{"type":"string","example":"PS-001,PS-002,PS-003"}},{"name":"format","in":"query","description":"`relational` returns a multi-sheet workbook with the line items on their own sheets; anything else returns the flat one-row-per-document sheet. A relational export is always XLSX, even with type=csv.","required":false,"schema":{"type":"string","default":"flat","enum":["flat","relational"]}}],"responses":{"200":{"description":"Up to the async threshold (config exports.async_threshold, default 100 rows) the file downloads directly. Above it the export is queued and a JSON notice comes back instead; the file is delivered by in-app and email notification.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"properties":{"queued":{"type":"boolean","example":true},"export_id":{"type":"string","example":"9d3c1f8e-2b7a-4c55-9a1e-3f6d2b8c7e10"},"message":{"type":"string","example":"Exporting 1,250 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The caller's role may not export payment statements.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Export failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Payment statements","x-fido-area-rank":5}},"/v1/finance/export/pro-formas":{"get":{"tags":["Finances"],"summary":"Export pro formas","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports pro forma data to a CSV file with optional filtering by specific pro forma IDs.","operationId":"ext_get_finance_export_pro_formas","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"ids","in":"query","description":"Comma-separated list of pro forma IDs to export. If not provided, exports all pro formas.","required":false,"schema":{"type":"string","example":"PF-001,PF-002,PF-003"}},{"name":"format","in":"query","description":"`relational` returns a multi-sheet workbook with the line items on their own sheets; anything else returns the flat one-row-per-document sheet. A relational export is always XLSX, even with type=csv.","required":false,"schema":{"type":"string","default":"flat","enum":["flat","relational"]}}],"responses":{"200":{"description":"Up to the async threshold (config exports.async_threshold, default 100 rows) the file downloads directly. Above it the export is queued and a JSON notice comes back instead; the file is delivered by in-app and email notification.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"properties":{"queued":{"type":"boolean","example":true},"export_id":{"type":"string","example":"9d3c1f8e-2b7a-4c55-9a1e-3f6d2b8c7e10"},"message":{"type":"string","example":"Exporting 1,250 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The caller's role may not export pro formas.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Export failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/financial-statuses":{"get":{"tags":["Finances"],"summary":"Get all financial statuses","operationId":"ext_get_finance_financial_statuses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"type","in":"query","description":"Filter statuses by module type","required":false,"schema":{"type":"string","enum":["invoice","proforma","payable","payment_statement"],"example":"invoice"}}],"responses":{"200":{"description":"Financial statuses retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Financial statuses retrieved successfully."},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"description":"Backend status name (always returned)","type":"string","example":"Sent"},"label":{"description":"Role-based display label: portal_display_label for client/provider, name for admin/scheduler","type":"string","example":"New"},"type":{"type":"string","example":"invoice"},"code":{"type":"string","example":"INVOICE_SENT"},"portal_display_label":{"description":"Portal display label (null for admin-only statuses)","type":"string","example":"New","nullable":true},"portal_visible":{"description":"Whether status is visible in portal for client/provider","type":"boolean","example":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler","x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/invoices":{"get":{"tags":["Finances"],"summary":"Retrieve a list of invoices","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of invoices based on search criteria, filters, and sorting options.","operationId":"ext_get_finance_invoices","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter invoices by specified columns.","required":false,"schema":{"type":"string","example":"INV-001"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search in (e.g., 'invoice,client,status,total').","required":false,"schema":{"type":"string","example":"invoice,client"}},{"name":"status","in":"query","description":"Filter invoices by status.","required":false,"schema":{"type":"string","enum":["draft","sent","paid","overdue","canceled"],"example":"paid"}},{"name":"clientId","in":"query","description":"Filter invoices by client ID.","required":false,"schema":{"type":"string","example":"CLT-12345"}},{"name":"isOrganizationInvoice","in":"query","description":"Filter by invoice ownership scope. true = organization invoices, false = client invoices.","required":false,"schema":{"type":"boolean","example":true}},{"name":"invoiceType","in":"query","description":"Filter by how the invoice was created: manual or system_generated (accepts enum value or label, e.g. system_generated or System generated).","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"startDate","in":"query","description":"Filter invoices created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter invoices created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"dueWithinDays","in":"query","description":"Filter invoices whose due_date falls within the next N days (today through today+N).","required":false,"schema":{"type":"integer","enum":[1,3,7],"example":7}},{"name":"sortBy","in":"query","description":"Sort invoices by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of invoices to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"isPublished","in":"query","description":"Filter by the Publication Status column: true for published, false for drafts.","required":false,"schema":{"type":"boolean","example":true}},{"name":"approvalStatus","in":"query","description":"Filter invoices by internal approval status.","required":false,"schema":{"type":"string","enum":["pending","approved","rejected","cancelled"],"example":"pending"}}],"responses":{"200":{"description":"Invoices retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"boolean","example":true},"paid_label":{"type":"string","example":"Paid in invoice","nullable":true},"isOrganizationInvoice":{"type":"boolean","example":true},"billTo":{"type":"string"},"clientsBreakdown":{"description":"Present for organization invoices with linked work items.","properties":{"clients":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"Client A"},"logo":{"type":"string","example":null,"nullable":true},"totalBilledAmount":{"type":"number","format":"float","example":250.5}},"type":"object"}},"totalBilledToClients":{"type":"number","format":"float","example":500.75}},"type":"object","nullable":true},"client":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"paymentTerms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"dueDate":{"type":"string","example":"2026-01-15","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"clientPaidAmount":{"type":"string"},"orgCoveredAmount":{"type":"number","example":0},"creditsApplied":{"type":"number","example":0},"balanceDue":{"type":"string"},"payableBalanceDue":{"type":"string"},"assignmentIds":{"type":"array","items":[],"nullable":true},"shiftIds":{"type":"array","items":[],"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0},"post":{"tags":["Finances"],"summary":"Create a new invoice","description":"**Required scope:** `finance:write`  \n**Roles:** admin, scheduler\n\nCreates an invoice. Work items (assignments/shifts) already paid for this client are excluded from services_charges. When duplicating (source_document_id), if the source is paid, amounts are zeroed unless full_copy=true (reverse-and-cancel reissue).","operationId":"ext_post_finance_invoices","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Creates an invoice, or saves an existing one when `id` is sent. Sent as multipart/form-data when a document file is attached. Fields marked 'required when published' are required only with is_published=true (the default). Saving an organization-generated invoice (is_org_invoice) accepts only id, notes, internal_notes, documents and the override fields.","required":["client_id","billable_entities"],"properties":{"override_locks":{"description":"Edit a paid document past its locks. Send on the retry after a save asks.","type":"boolean","nullable":true},"override_reason":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"nullable":true},"confirmation":{"description":"Confirms the resend prompt a save on a sent document raises.","type":"boolean","nullable":true},"resend_delivery":{"type":"string","enum":["send_updated","internal_only","send_now","save_only"],"nullable":true},"overpayment_confirmation":{"description":"Accept a payment that exceeds the balance due.","type":"boolean","nullable":true},"id":{"description":"Existing invoice to save. Omit to create.","type":"string","example":"INV-EWDM3W","nullable":true},"client_id":{"description":"The client billed. id is a CLT- user id.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"source_document_id":{"description":"Invoice being duplicated. If it is paid (status Paid or balance due <= 0), amounts are zeroed unless full_copy=true.","type":"string","example":"INV-ABC123","nullable":true},"full_copy":{"description":"Keep full charges when duplicating a paid invoice (reverse-and-cancel reissue).","type":"boolean","example":false,"nullable":true},"billable_entities":{"description":"Work items billed. Work items already paid for this client are left out of the service charges.","type":"array","items":{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-YZXCIT"}},"type":"object"}},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"nullable":true},"line_items":{"description":"type.id is credit, charges or reimbursement.","type":"array","items":{"description":"A manual line on a finance document, on top of the charges its work items carry.","required":["amount"],"properties":{"name":{"type":"string","maxLength":255,"example":"Parking reimbursement","nullable":true},"description":{"type":"string","maxLength":1000,"nullable":true},"amount":{"type":"number","minimum":0,"example":25},"type":{"description":"The allowed ids depend on the document type.","properties":{"id":{"type":"string","example":"charges"},"label":{"type":"string","example":"Additional Charge","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"summary":{"description":"Tax type and amount become required when the organization charges tax on invoices.","properties":{"tax_type":{"properties":{"id":{"type":"string","enum":["Fixed","Percentage"],"example":"Percentage"},"label":{"type":"string","example":"Percentage"}},"type":"object","nullable":true},"tax_amount":{"type":"number","minimum":0,"example":8.25,"nullable":true},"discount_type":{"properties":{"id":{"type":"string","enum":["Fixed","Percentage"],"example":"Fixed"},"label":{"type":"string","example":"Fixed"}},"type":"object","nullable":true},"discount_amount":{"type":"number","minimum":0,"example":10,"nullable":true},"payments_applied":{"type":"number","minimum":0,"nullable":true}},"type":"object"},"status":{"description":"Financial status. id required when saving an existing published invoice.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"payment_terms":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","format":"date","example":"2025-01-15","nullable":true},"due_date":{"description":"Required when published; on or after issue_date.","type":"string","format":"date","example":"2025-01-30","nullable":true},"notes":{"description":"Shown to the client.","type":"string","maxLength":2000,"nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"is_published":{"description":"Defaults to true. false saves a draft.","type":"boolean","example":true,"nullable":true},"documents":{"type":"array","items":{"description":"A document on an assignment, shift or request.","type":"object","allOf":[{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},{"properties":{"isPublic":{"description":"Visible to the client and consumer, not only to staff.","type":"boolean","example":false,"nullable":true}},"type":"object"}]},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Existing invoice saved (id was sent).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice updated successfully."},"data":{"properties":{"id":{"type":"string","example":"INV-EWDM3W"}},"type":"object"}},"type":"object"}}}},"201":{"description":"Invoice created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice created successfully."},"data":{"properties":{"id":{"type":"string","example":"INV-EWDM3W"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The caller may not save this invoice.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A status change that needs confirmation also comes back as 422, with requires_confirmation=true and data {current_status, target_status, payment_details}; resend with the confirmation fields to proceed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"client_id":["Client is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Invoice creation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred ? please try again."}},"type":"object"}}}},"503":{"description":"The invoice was saved but could not be moved to Sent.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The document could not be set to Sent. Please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/invoices-details":{"get":{"tags":["Finances"],"summary":"Get detailed information for multiple invoices","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves comprehensive details for multiple invoices including client information, assignments, shifts, financial summary, and line items. Used for selecting invoices to include in pro-formas.","operationId":"ext_get_finance_invoices_details","parameters":[{"name":"ids","in":"query","description":"Comma-separated list of Invoice IDs to get details for","required":true,"schema":{"type":"string","example":"INV-12345,INV-67890"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Invoice details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice details retrieved successfully"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"INV-12345"},"client":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"Acme Corporation"},"email":{"type":"string","example":"contact@acme.com"},"phone":{"type":"string","example":"(123) 456-7890"}},"type":"object"},"financialSummary":{"properties":{"totalInvoiceAmount":{"type":"number","format":"float","example":1250.5}},"type":"object"},"status":{"type":"string","example":"Sent"},"total":{"type":"number","format":"float","example":1250.5},"is_paid":{"description":"True if this invoice is paid (status INVOICE_PAID or balance_due <= 0 and client_paid_amount > 0). Exclude it from the pro forma total and charges.","type":"boolean","example":false},"paid_label":{"description":"'Paid in invoice' when is_paid is true; null otherwise.","type":"string","example":null,"nullable":true}},"type":"object"}}},"type":"object"}}}},"400":{"description":"Missing required parameter","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Missing required parameter: ids"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/invoices/by-client/{client_id}":{"get":{"tags":["Finances"],"summary":"Retrieve invoices by client ID","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches all matching invoices for a specific client with filtering and sorting options (no pagination). Excludes invoices that are the conversion result of a pro forma (not selectable again for pro forma line-up).","operationId":"ext_get_finance_invoices_by_client_By_client_id","parameters":[{"name":"client_id","in":"path","description":"Client ID","required":true,"schema":{"type":"string","example":"CLT-12345"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"search","in":"query","description":"Search query to filter invoices","required":false,"schema":{"type":"string","example":"INV-001"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search in (e.g., 'invoice,client,status,total')","required":false,"schema":{"type":"string","example":"invoice,status"}},{"name":"statusId","in":"query","description":"Filter by status ID","required":false,"schema":{"type":"integer","example":1}},{"name":"startDate","in":"query","description":"Filter from this date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter until this date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort by field","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"invoiceType","in":"query","description":"Filter by how the invoice was created: manual or system_generated.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"proformaId","in":"query","description":"Pro forma being viewed or edited. Canceled/void invoices already selected into this pro forma are returned as well; canceled/void invoices selected into any other pro forma are not. Omit it and canceled/void invoices are excluded entirely.","required":false,"schema":{"type":"string","example":"PRF-8LE81N"}}],"responses":{"200":{"description":"Invoices retrieved successfully (non-paginated list)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoices retrieved successfully."},"data":{"description":"Every invoice for the client. This endpoint does not paginate, so no meta block is sent.","type":"array","items":{"properties":{"id":{"type":"string","example":"INV-QKPWQ9"},"is_paid":{"type":"boolean","example":true},"paid_label":{"type":"string","example":"Paid in invoice","nullable":true},"isOrganizationInvoice":{"type":"boolean","example":false},"billTo":{"type":"string","example":"client","nullable":true},"client":{"properties":{"id":{"type":"string","example":"CLT-N3B72G"},"name":{"type":"string","example":"Example label"},"email":{"type":"string","nullable":true},"logo":{"type":"string","nullable":true},"onlineStatus":{"type":"string","nullable":true}},"type":"object"},"paymentTerms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object"},"issueDate":{"type":"string","example":"01/15/2025","nullable":true},"dueDate":{"type":"string","example":"01/30/2025","nullable":true},"taxPercentage":{"type":"number","format":"float","example":8.25,"nullable":true},"discountAmount":{"type":"number","format":"float","example":0,"nullable":true},"subtotal":{"type":"number","format":"float","example":1250.5},"clientPaidAmount":{"type":"number","format":"float","example":250},"orgCoveredAmount":{"type":"number","format":"float","example":0},"creditsApplied":{"type":"number","format":"float","example":0},"balanceDue":{"type":"number","format":"float","example":1000.5},"payableBalanceDue":{"type":"number","format":"float","example":0,"nullable":true},"assignmentIds":{"type":"array","items":{"type":"string","example":"ASG-SA2IVL"}},"shiftIds":{"type":"array","items":{"type":"string","example":"SFT-9D2KQ1"}},"clientsBreakdown":{"description":"Present for organization invoices with linked work items.","properties":{"clients":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-N3B72G"},"name":{"type":"string","example":"Example label"},"logo":{"type":"string","nullable":true},"totalBilledAmount":{"type":"number","format":"float","example":250.5}},"type":"object"}},"totalBilledToClients":{"type":"number","format":"float","example":500.75}},"type":"object","nullable":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Client not found or no invoices found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/invoices/payment-history/by-client/{client_id}":{"get":{"tags":["Finances"],"summary":"Get payment history by client ID","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of payment history for a specific client.","operationId":"ext_get_finance_invoices_payment_history_by_client_By_client_id","parameters":[{"name":"client_id","in":"path","description":"Client ID","required":true,"schema":{"type":"string","example":"CLT-12345"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"search","in":"query","description":"Search query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by payment status","required":false,"schema":{"type":"string","example":"paid"}},{"name":"startDate","in":"query","description":"Filter from this date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"Filter until this date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"sortBy","in":"query","description":"Sort by field","required":false,"schema":{"type":"string","example":"payment_date"}},{"name":"sortOrder","in":"query","description":"Sort order","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Payment history retrieved successfully.","content":{"application/json":{"schema":{"description":"A paginated list. The envelope carries no message key on this endpoint.","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":42},"paymentDate":{"description":"Formatted with the organization's date format.","type":"string","example":"01/20/2025","nullable":true},"amount":{"type":"number","format":"float","example":250},"assignment":{"description":"Title of the first work item on the invoice, or N/A.","type":"string","example":"N/A"},"assignmentId":{"description":"Carries the invoice id, or N/A.","type":"string","example":"INV-QKPWQ9"},"invoiceId":{"type":"string","example":"INV-QKPWQ9"},"status":{"type":"string","example":"Completed"},"paymentMethod":{"description":"Title-cased, or N/A when none is recorded.","type":"string","example":"Bank Transfer"},"transactionId":{"type":"string","example":"txn_1A2B3C","nullable":true},"notes":{"type":"string","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":4},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":37}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/invoices/{id}":{"delete":{"tags":["Finances"],"summary":"Delete an invoice","operationId":"ext_delete_finance_invoices_By_id","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"string","example":"INV-A0XJRY"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Invoice deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Invoice not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invoice not found."}},"type":"object"}}}},"422":{"description":"Delete not allowed — issued document, financial activity, or completed refund","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Cannot delete this invoice after a refund. Use Cancel or Void."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Invoice deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred ? please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:delete","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `finance:delete`  \n**Roles:** admin, scheduler","x-fido-area":"Invoices","x-fido-area-rank":0},"get":{"tags":["Finances"],"summary":"Retrieve a specific invoice","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches detailed information about a specific invoice including line items, assignments, and attachments.","operationId":"ext_get_finance_invoices_By_id","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"string","example":"INV-1T4MQI"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"for_duplicate","in":"query","description":"If true, automatically zero amounts if the invoice is paid (for duplication purposes). Use with full_copy=true after reverse-and-cancel to keep full charges.","required":false,"schema":{"type":"boolean","example":false}},{"name":"full_copy","in":"query","description":"When used with for_duplicate=true, skip Paid amount zeroing (full-copy reissue after reverse_and_cancel).","required":false,"schema":{"type":"boolean","example":false}}],"responses":{"200":{"description":"Invoice retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"client_id":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label"},"onlineStatus":{"type":"string","example":"online"}},"type":"object","nullable":true},"isOrganizationInvoice":{"type":"boolean","example":true},"billTo":{"type":"string"},"selectedInvoiceSummary":{"type":"object"},"id":{"type":"string","example":"INV-EWDM3W"},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"status":{"description":"Financial status: id, label and code, plus display details.","type":"object","nullable":true},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"billable_entities":{"description":"Linked assignments and shifts, with is_deleted when the work item was removed.","type":"array","items":{"type":"object"},"nullable":true},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"paymentSection":{"description":"Present when the caller can pay or record a payment.","type":"object","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Invoice not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invoice not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0},"put":{"tags":["Finances"],"summary":"Update invoice inline fields","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdates one or more fields from the list or detail screen without a full save: payment terms, financial status, due date, published flag, or a partial payment. Every field is optional; only the ones sent change.","operationId":"ext_put_finance_invoices_By_id","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"string","example":"INV-EWDM3W"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"Idempotency-Key","in":"header","description":"Retry key for a partial payment, max 255 characters. Wins over the body's idempotency_key. A partial payment needs this or transaction_id.","required":false,"schema":{"type":"string","example":"b2f6c1d4-8e0a-4b8b-9c1d-2a7e5f3c9d10"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"override_locks":{"description":"Edit a paid document past its locks. Send on the retry after a save asks.","type":"boolean","nullable":true},"override_reason":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"nullable":true},"confirmation":{"description":"Confirms the resend prompt a save on a sent document raises.","type":"boolean","nullable":true},"resend_delivery":{"type":"string","enum":["send_updated","internal_only","send_now","save_only"],"nullable":true},"overpayment_confirmation":{"description":"Accept a payment that exceeds the balance due.","type":"boolean","nullable":true},"payment_terms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Net 15"},"isCustom":{"type":"boolean","example":false,"nullable":true}},"type":"object","nullable":true},"status":{"description":"Target financial status. A move that needs confirmation returns 422 with requires_confirmation=true.","properties":{"id":{"type":"integer","example":4},"label":{"type":"string","example":"Paid"},"isCustom":{"type":"boolean","example":false,"nullable":true}},"type":"object","nullable":true},"due_date":{"type":"string","format":"date","example":"2025-03-15"},"reason":{"description":"Why the status changed, such as a rejection reason.","type":"string","maxLength":500,"nullable":true},"is_published":{"type":"boolean","example":false},"partial_payment_amount":{"description":"Records a partial payment. Requires the Idempotency-Key header, idempotency_key or transaction_id.","type":"number","minimum":0,"exclusiveMinimum":true,"example":50,"nullable":true},"payment_amount":{"type":"number","minimum":0,"exclusiveMinimum":true,"nullable":true},"payment_method":{"type":"string","maxLength":50,"example":"check","nullable":true},"transaction_id":{"type":"string","maxLength":255,"example":"CHK-10042","nullable":true},"idempotency_key":{"description":"Body fallback for the Idempotency-Key header.","type":"string","maxLength":255,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Invoice updated successfully. Each field is present only when it applies.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice updated successfully."},"data":{"properties":{"id":{"type":"string","example":"INV-EWDM3W"},"payment_terms":{"description":"Echo of the payment_terms sent.","properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Net 15"}},"type":"object"},"status":{"description":"The status after the change, when it changed.","properties":{"id":{"type":"integer","example":2},"name":{"type":"string","example":"Sent"}},"type":"object"},"due_date":{"type":"string","example":"2025-03-15"},"is_published":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Invoice not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invoice not found."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"payment_terms":["Payment terms are invalid."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Invoice update failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred ? please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/invoices/{id}/mark-viewed":{"patch":{"tags":["Finances"],"summary":"Mark invoice as viewed","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdates the invoice status to 'Viewed' when a client views the invoice.","operationId":"ext_patch_finance_invoices_By_id_mark_viewed","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"string","example":"INV-1T4MQI"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Invoice marked as viewed successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice marked as viewed."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Invoice not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invoice not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/my-invoices":{"get":{"tags":["Finances"],"summary":"Retrieve invoices for the authenticated user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler\n\nFetches a paginated list of invoices for the current user based on their role (client or provider).","operationId":"ext_get_finance_my_invoices","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"search","in":"query","description":"Search query to filter invoices by invoice number, client name, or email.","required":false,"schema":{"type":"string","example":"INV-001"}},{"name":"status","in":"query","description":"Filter invoices by status.","required":false,"schema":{"type":"string","enum":["draft","sent","paid","overdue","canceled"],"example":"paid"}},{"name":"invoiceType","in":"query","description":"Filter by how the invoice was created: manual or system_generated.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"startDate","in":"query","description":"Filter invoices created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter invoices created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort invoices by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of invoices to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"dueWithinDays","in":"query","description":"Filter invoices whose due_date falls within the next N days (today through today+N).","required":false,"schema":{"type":"integer","enum":[1,3,7],"example":7}}],"responses":{"200":{"description":"Invoices retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"boolean","example":true},"paid_label":{"type":"string","example":"Paid in invoice","nullable":true},"isOrganizationInvoice":{"type":"boolean","example":true},"billTo":{"type":"string"},"clientsBreakdown":{"type":"string"},"client":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"paymentTerms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"dueDate":{"type":"string","example":"2026-01-15","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"clientPaidAmount":{"type":"string"},"orgCoveredAmount":{"type":"number","example":0},"creditsApplied":{"type":"number","example":0},"balanceDue":{"type":"string"},"payableBalanceDue":{"type":"string"},"assignmentIds":{"type":"array","items":[],"nullable":true},"shiftIds":{"type":"array","items":[],"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/my-invoices/{id}":{"get":{"tags":["Finances"],"summary":"Retrieve specific invoice for logged-in client user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler\n\nFetches detailed information about a specific invoice for the authenticated client user only.","operationId":"ext_get_finance_my_invoices_By_id","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"string","example":"INV-1T4MQI"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Invoice retrieved successfully. Same shape as GET /finance/invoices/{id}, without staff-only fields.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"client_id":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"onlineStatus":{"type":"string","nullable":true}},"type":"object"},"isOrganizationInvoice":{"type":"boolean"},"billTo":{"type":"object","nullable":true},"selectedInvoiceSummary":{"type":"object"},"id":{"type":"string","example":"INV-EWDM3W"},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"status":{"description":"Financial status: id, label and code, plus display details.","type":"object","nullable":true},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"billable_entities":{"description":"Linked assignments and shifts, with is_deleted when the work item was removed.","type":"array","items":{"type":"object"},"nullable":true},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"paymentSection":{"description":"Present when the caller can pay or record a payment.","type":"object","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Invoice not found, not published, or not billed to the caller","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Invoices","x-fido-area-rank":0}},"/v1/finance/my-payables":{"get":{"tags":["Finances"],"summary":"Retrieve payables for the authenticated user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler\n\nFetches a paginated list of payables for the current user based on their role (provider).","operationId":"ext_get_finance_my_payables","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"search","in":"query","description":"Search query to filter payables by payable number, provider name, or email.","required":false,"schema":{"type":"string","example":"PAY-001"}},{"name":"status","in":"query","description":"Filter payables by status.","required":false,"schema":{"type":"string","enum":["draft","approved","partially_paid","paid","canceled"],"example":"paid"}},{"name":"type","in":"query","description":"Filter by document generation type (manual or system_generated). Same as payableType; takes precedence if both are sent.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"payableType","in":"query","description":"Filter by manual vs system_generated. Ignored if type is set.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"startDate","in":"query","description":"Filter payables created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter payables created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort payables by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of payables to retrieve per page.","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Payables retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"number","example":0},"paid_label":{"type":"string","example":"Paid in payable","nullable":true},"provider":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"paymentTerms":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"value":{"type":"string","nullable":true}},"type":"object","nullable":true},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"dueDate":{"type":"string","example":"2026-01-15","nullable":true},"approvedAt":{"type":"string","example":"2026-01-15 09:00:00","nullable":true},"approvalDate":{"type":"string","example":"2026-01-15","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"paidAmount":{"type":"number","example":0},"balanceDue":{"type":"number","example":0},"assignmentIds":{"type":"array","items":[],"nullable":true},"shiftIds":{"type":"array","items":[],"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/my-payables/{id}":{"get":{"tags":["Finances"],"summary":"Retrieve specific payable for logged-in provider user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler\n\nFetches detailed information about a specific payable for the authenticated provider user only.","operationId":"ext_get_finance_my_payables_By_id","parameters":[{"name":"id","in":"path","description":"Payable ID","required":true,"schema":{"type":"string","example":"PAY-1T4MQI"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Payable retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"id":{"type":"string","example":"PAY-ABC123"},"provider":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"status":{"type":"string","example":"paid"},"issueDate":{"type":"string","format":"date","example":"2025-01-01"},"approvalDate":{"type":"string","format":"date","example":"2025-01-15"},"subtotal":{"type":"number","format":"float","example":150},"taxAmount":{"type":"number","format":"float","example":15},"taxPercentage":{"type":"number","format":"float","example":10},"discountAmount":{"type":"number","format":"float","example":10},"total":{"type":"number","format":"float","example":160},"paidAmount":{"type":"number","format":"float","example":160},"balanceDue":{"type":"number","format":"float","example":0},"notes":{"type":"string","example":"Approved for provider payout"},"paymentAcknowledgedAt":{"description":"Formatted like issue_date/paid_at via presentation settings (admin: Y-m-d H:i:s; portal: org date format).","type":"string","example":"2026-07-31 12:00:00","nullable":true},"paymentAcknowledgedBy":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Provider"},"image":{"type":"string","example":null,"nullable":true}},"type":"object","nullable":true},"lineItems":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"title":{"type":"string","example":"Shift Payment"},"description":{"type":"string","example":"Payment for shift work"},"quantity":{"type":"number","format":"float","example":1},"unitPrice":{"type":"number","format":"float","example":150},"total":{"type":"number","format":"float","example":150}},"type":"object"}},"billable_entities":{"type":"array","items":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"is_deleted":{"type":"boolean","example":false}},"type":"object"}},"billable_entities_pay_calc":{"type":"array","items":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"isCustom":{"type":"boolean","example":false}},"type":"object","nullable":true},"derived_hours_used_for_pay":{"type":"number","format":"float","nullable":true},"hours_used_for_pay":{"type":"number","format":"float","nullable":true},"is_hours_overridden":{"type":"boolean","example":false},"derived_pay_rate":{"type":"number","format":"float","nullable":true},"pay_rate":{"type":"number","format":"float","nullable":true},"is_pay_rate_overridden":{"type":"boolean","example":false},"services_charge":{"type":"number","format":"float","nullable":true},"pay_rate_breakdown":{"properties":{"base_rate":{"type":"number","format":"float","example":45},"base_hours":{"type":"number","format":"float","example":8},"rules_applied":{"type":"array","items":{"type":"object"}},"rate_lines":{"type":"array","items":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}},"summary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"effective_pay_rate":{"type":"number","format":"float","example":46.67},"total_service_charge":{"type":"number","format":"float","example":360},"source":{"description":"Which time basis priced the lines — not where the rate came from; see rate_source.","type":"string","enum":["check_in","estimated_pay"]},"rate_source":{"description":"Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"description":"Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.","type":"string","example":"Provider Pay Rate","nullable":true},"rate_source_description":{"type":"string","example":"Driven by this provider's own custom pay rate configuration.","nullable":true},"rate_source_is_mixed":{"description":"True when the lines were priced from more than one rate configuration.","type":"boolean","example":false},"rate_configuration":{"description":"Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows.","properties":{"source":{"description":"Null when the work item was priced from more than one configuration.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"label":{"type":"string","example":"Default Pay Rate","nullable":true},"description":{"type":"string","example":"Driven by the organization default provider pay rate configuration.","nullable":true},"is_mixed":{"type":"boolean","example":false},"rows":{"type":"array","items":{"properties":{"service_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"service_provider_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"rate_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"site_type":{"type":"string","example":"onsite_client","nullable":true},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","enum":["hr","min"],"example":"hr"},"source":{"type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"rate_rules_suppressed":{"type":"boolean","example":false},"hours_override_reason":{"description":"Latest hours override reason (mirrors save input when is_hours_overridden).","type":"string","nullable":true},"pay_rate_override_reason":{"description":"Latest pay rate override reason (mirrors save input when is_pay_rate_overridden).","type":"string","nullable":true}},"type":"object"}},"attachments":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"fileName":{"type":"string","example":"payable.pdf"},"filePath":{"type":"string","example":"path/to/file"}},"type":"object"}},"compensation_summary":{"description":"Compensation breakdown for this payable","properties":{"workitems":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-002-01"},"name":{"type":"string","example":"Medical Appointment"},"type":{"type":"string","example":"assignment"},"pay_time_basis":{"type":"string","example":"scheduled_time","nullable":true},"hours_used_for_pay":{"type":"number","format":"float","example":14.5},"pay_rate":{"type":"number","format":"float","example":25},"services_charge":{"type":"number","format":"float","example":362.5},"hours":{"type":"number","format":"float","example":14.5},"rate":{"type":"number","format":"float","example":25},"unit":{"type":"string","example":"hour"},"expenses_total":{"type":"number","format":"float","example":37.5},"all_expenses_total":{"description":"Sum of all provider expenses for this work item across all statuses","type":"number","format":"float","example":60},"service_cost":{"type":"number","format":"float","example":362.5},"total_payment":{"type":"number","format":"float","example":400},"expenses_breakdown":{"description":"Per-expense breakdown for this work item","type":"array","items":{"properties":{"expense_id":{"description":"Provider expense row id","type":"integer","example":1},"id":{"description":"Reimbursable expense template id (0 for custom)","type":"integer","example":10},"name":{"type":"string","example":"Mileage Reimbursement"},"rate":{"type":"number","format":"float","example":0.58},"isCustom":{"type":"boolean","example":false},"unit":{"type":"string","example":"mile"},"amount":{"description":"Aligned display amount for breakdown row","type":"number","format":"float","example":17.5},"submitted_amount":{"type":"number","format":"float","example":17.5},"status":{"type":"string","example":"pending","nullable":true},"uploadReceipt":{"type":"string","example":"https://s3.example.com/.../receipt.pdf","nullable":true}},"type":"object"}}},"type":"object"}},"service_cost":{"type":"number","format":"float","example":400},"expenses_total":{"description":"Approved expenses total (used in total)","type":"number","format":"float","example":37.5},"all_expenses_total":{"description":"All expenses total across all statuses","type":"number","format":"float","example":60},"total":{"type":"number","format":"float","example":865},"payable_status":{"type":"string","example":"Payable Approved","nullable":true}},"type":"object"},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"paymentSection":{"description":"Present when the caller can pay or record a payment.","type":"object","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payable not found or not owned by user","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payable not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/my-payment-statements":{"get":{"tags":["Finances"],"summary":"Retrieve payment statements for the authenticated user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler\n\nFetches a paginated list of payment statements for the current user based on their role (provider).","operationId":"ext_get_finance_my_payment_statements","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"search","in":"query","description":"Search query to filter payment statements by payment statement number, provider name, or email.","required":false,"schema":{"type":"string","example":"PS-001"}},{"name":"status","in":"query","description":"Filter payment statements by status.","required":false,"schema":{"type":"string","enum":["generated","sent","confirmed","disputed","void"],"example":"sent"}},{"name":"type","in":"query","description":"Filter by document generation type (manual or system_generated). Same as paymentStatementType; takes precedence if both are sent.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"paymentStatementType","in":"query","description":"Filter by manual vs system_generated. Ignored if type is set.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"startDate","in":"query","description":"Filter payment statements created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter payment statements created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort payment statements by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of payment statements to retrieve per page.","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Payment statements retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"boolean","example":true},"paid_label":{"type":"string","example":"Paid in payment statement","nullable":true},"provider":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"paymentTerms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"expiryDate":{"type":"string","example":"2026-01-15","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"paidAmount":{"type":"string"},"balanceDue":{"type":"number","example":0},"payableIds":{"description":"Selected payables on the payment statement with per-item portal linkability","type":"array","items":{"properties":{"id":{"type":"string","example":"PAYB-ABC123"},"portal_accessible":{"description":"When false, hide View in provider portal and render inline from selectedPayablesSummary on detail","type":"boolean","example":false}},"type":"object"}},"assignmentIds":{"type":"array","items":[]},"shiftIds":{"type":"array","items":[]}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-area":"Payment statements","x-fido-area-rank":5}},"/v1/finance/my-payment-statements/{id}":{"get":{"tags":["Finances"],"summary":"Retrieve specific payment statement for logged-in provider user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler\n\nFetches detailed information about a specific payment statement for the authenticated provider user only.","operationId":"ext_get_finance_my_payment_statements_By_id","parameters":[{"name":"id","in":"path","description":"Payment statement ID","required":true,"schema":{"type":"string","example":"PS-1T4MQI"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Payment statement retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payment statement retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"id":{"type":"string","example":"PS-ABC123"},"provider":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"status":{"type":"string","example":"sent"},"issueDate":{"type":"string","format":"date","example":"2025-01-01"},"dueDate":{"type":"string","format":"date","example":"2025-01-15"},"subtotal":{"type":"number","format":"float","example":150},"taxAmount":{"type":"number","format":"float","example":15},"taxPercentage":{"type":"number","format":"float","example":10},"discountAmount":{"type":"number","format":"float","example":10},"total":{"type":"number","format":"float","example":160},"paidAmount":{"type":"number","format":"float","example":160},"balanceDue":{"type":"number","format":"float","example":0},"notes":{"type":"string","example":"Payment due within 30 days"},"lineItems":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Reimbursement"},"description":{"type":"string","example":"Reimbursement for travel expenses"},"amount":{"type":"number","format":"float","example":150},"type":{"type":"string","example":"reimbursement"}},"type":"object"}},"payables":{"type":"array","items":{"properties":{"id":{"type":"string","example":"PAY-12345"},"payableNumber":{"type":"string","example":"PAY-001"}},"type":"object"}},"billable_entities":{"type":"array","items":{"properties":{"type":{"type":"string","example":"payable"},"id":{"type":"string","example":"PAYB-ABC123"},"portal_accessible":{"type":"boolean","example":false}},"type":"object"}},"selectedPayablesSummary":{"description":"Expanded included-payable cards, also used as the inline payable breakdown when portal_accessible is false. Structural parity with pro forma selectedInvoicesSummary. Admin/scheduler get approvalStatus + requiresApproval; providers get portal-facing status only. Each assignment/shift includes serviceRateBreakdown, itemized expenses and adminFeeBreakdown from the work-items billing read. financialSummary carries additionalItems, credits, totalPayableAmount and balance_due; paymentHistory lists partial payments issued. `status` is the portal-facing string and `financialSummary.tax` the scalar amount; `statusDetail` and `financialSummary.taxDetail` expose the richer objects.","type":"array","items":{"properties":{"id":{"type":"string","example":"PAYB-ABC123"},"portal_accessible":{"type":"boolean","example":false},"balanceApplied":{"description":"Amount this payable contributes to the statement total","type":"number","example":1250}},"type":"object"}},"attachments":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"fileName":{"type":"string","example":"payment-statement.pdf"},"filePath":{"type":"string","example":"path/to/file"}},"type":"object"}},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"paymentSection":{"description":"Present when the caller can pay or record a payment.","type":"object","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payment statement not found or not owned by user","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payment statement not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-area":"Payment statements","x-fido-area-rank":5}},"/v1/finance/my-proforma/{id}":{"get":{"tags":["Finances"],"summary":"Retrieve specific pro forma for logged-in client user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler\n\nFetches detailed information about a specific pro forma for the authenticated client user only.","operationId":"ext_get_finance_my_proforma_By_id","parameters":[{"name":"id","in":"path","description":"Pro forma ID","required":true,"schema":{"type":"string","example":"PF-1T4MQI"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Pro forma retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"billable_entities":{"type":"array","items":{"properties":{"type":{"type":"string","example":"invoice"},"id":{"type":"string","example":"INV-ABC123"},"portal_accessible":{"type":"boolean","example":false}},"type":"object"}},"selectedInvoicesSummary":{"description":"Expanded included-invoice cards. Same item shape as invoice detail selectedInvoiceSummary. Admin/scheduler get is_published + approvalStatus; clients get portal-facing status only. Each assignment/shift includes serviceRateBreakdown, expenses, and adminFeeBreakdown from the work-items billing read.","type":"array","items":{"type":"object"}},"converted_invoice":{"properties":{"id":{"type":"string","example":"INV-NEW123"},"portal_accessible":{"type":"boolean","example":true}},"type":"object","nullable":true},"id":{"type":"string","example":"INV-EWDM3W"},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"status":{"description":"Financial status: id, label and code, plus display details.","type":"object","nullable":true},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"paymentSection":{"description":"Present when the caller can pay or record a payment.","type":"object","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Pro forma not found or not owned by user","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/my-proformas":{"get":{"tags":["Finances"],"summary":"Retrieve pro formas for the authenticated user","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler\n\nFetches a paginated list of pro formas for the current user (client) based on their role.","operationId":"ext_get_finance_my_proformas","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"search","in":"query","description":"Search query to filter pro formas by pro forma number, client name, or email.","required":false,"schema":{"type":"string","example":"PRF-001"}},{"name":"status","in":"query","description":"Filter pro formas by status.","required":false,"schema":{"type":"string","enum":["draft","sent","approved","rejected","converted"],"example":"sent"}},{"name":"type","in":"query","description":"Filter by document generation type (manual or system_generated). Same as proformaType; takes precedence if both are sent.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"proformaType","in":"query","description":"Filter by manual vs system_generated. Ignored if type is set.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"startDate","in":"query","description":"Filter pro formas created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter pro formas created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort pro formas by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of pro formas to retrieve per page.","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Pro formas retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"boolean","example":true},"paid_label":{"type":"string","example":"Paid in pro forma","nullable":true},"client":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"dueDate":{"type":"string","example":"2026-01-15","nullable":true},"paymentTerms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"balanceDue":{"type":"number","example":0},"expiryDate":{"type":"string","example":"2026-01-15","nullable":true},"isExpired":{"type":"boolean","example":true},"invoiceIds":{"description":"Selected invoices on the pro forma with per-item portal linkability","type":"array","items":{"properties":{"id":{"type":"string","example":"INV-ABC123"},"portal_accessible":{"description":"When false, hide View in client portal and render inline from selectedInvoicesSummary on detail","type":"boolean","example":false}},"type":"object"}},"assignmentIds":{"type":"array","items":[]},"shiftIds":{"type":"array","items":[]}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/overview":{"get":{"tags":["Finances"],"summary":"Get financial overview data","description":"**Required scope:** `finance:read`\n\nRetrieves financial overview data including chart time-series data and summary cards. The response adapts based on the authenticated user's role: Admin/Scheduler see organization-level data (all invoices + payables), Providers see provider-specific payables data, and Clients see client-specific invoices data. Supports filtering by time period and date range. Returns two types of summaries: 'summary' (overall all-time totals) and 'periodSummary' (totals filtered by selected period/date range). A Scheduler without Finances Read gets an empty result (200, empty `data`, `meta.total` 0, the reason in `message`) rather than 403, since the dashboard shows it to every Scheduler.","operationId":"ext_get_finance_overview","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"period","in":"query","description":"Time period for grouping data. all=last 10 years by month; today=hourly buckets for current day; this_week/this_month=single week/month by day; daily=last 30 days; weekly=last 12 weeks; monthly=last 12 months.","required":false,"schema":{"type":"string","default":"daily","enum":["all","today","this_week","this_month","daily","weekly","monthly"],"example":"daily"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"type","in":"query","description":"Filter by type. For Admin/Scheduler: invoicing or payments (if not specified, returns all available overview types). For Clients: invoicing (Invoice tab, default) or proforma (Pro Forma tab). For Providers: payables (Payables tab, default) or payment_statement (Payment Statements tab).","required":false,"schema":{"type":"string","enum":["invoicing","payments","proforma","payables","payment_statement"],"example":"invoicing"}},{"name":"status","in":"query","description":"Additional financial_statuses.code / snapshot codes to include in 'summary' on top of the always-on default cards (Outstanding, Overdue, Partially Paid, Paid, Pro Forma Outstanding, Pro Forma Overdue for invoicing; Pending Payables, Approved, Payment Issued, Partially Paid, Paid, Payment Statement Outstanding for payments). Only 'summary' (all-time) is affected — 'periodSummary' and the chart series always stay the fixed default set. For type=invoicing, also accepts every individual invoice status (INVOICE_PREPARED, INVOICE_SENT, INVOICE_VIEWED, INVOICE_REFUNDED, INVOICE_CANCELED, INVOICE_VOID) and pro forma status (PROFORMA_PREPARED, PROFORMA_SENT, PROFORMA_VIEWED, PROFORMA_REJECTED) plus snapshot card PROFORMA_PAID (payment_rollup Paid amount bucket, not a lifecycle status), Mka note pro forma statuses are always their own separate cards on the invoicing tab (e.g. 'Prepared' and 'Pro Forma Prepared' never combine into one number), and PROFORMA_ACCEPTED is not available here at all since Pro Forma Accepted only exists on the dedicated type=proforma tab. For type=payments, also accepts every individual payable status (PAYABLE_PREPARED, PAYABLE_REVIEWED, PAYABLE_CANCELED, PAYABLE_VOID) and payment statement status (PAYMENT_STATEMENT_PREPARED, PAYMENT_STATEMENT_SENT, PAYMENT_STATEMENT_VIEWED, PAYMENT_STATEMENT_CANCELED, PAYMENT_STATEMENT_VOID) plus snapshot cards PAYMENT_STATEMENT_PAID / PAYMENT_STATEMENT_PARTIALLY_PAID (payment_rollup amount buckets, not lifecycle statuses). Pass repeated as status[]=CODE or as a single comma-separated value. Alternatively pass status=ALL (or status[]=ALL) to back the 'View all' button — returns every card for the active tab instead of enumerating individual codes.","required":false,"schema":{"type":"array","items":{"type":"string"},"example":["ALL"]}}],"responses":{"200":{"description":"Financial overview retrieved successfully. Response structure varies by role: Admin/Scheduler returns invoicing + payables + proforma data (or selected type), Provider returns payables only, Client returns invoices only. The 'summary' field contains overall totals (all-time, not filtered by date range), while 'periodSummary' contains totals for the selected period/date range (calculated from chart series data). Both only include default cards unless additional codes are requested via 'statuses'.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Financial overview retrieved successfully"},"data":{"properties":{"chart":{"properties":{"series":{"type":"array","items":{"properties":{"name":{"type":"string","example":"Outstanding"},"data":{"type":"array","items":{"type":"number"},"example":[137,210,160]},"total":{"description":"Sum of 'data' across all categories for this series.","type":"number","example":507}},"type":"object"}},"categories":{"type":"array","items":{"type":"string"},"example":["Jan 1","Jan 2","Jan 3"]}},"type":"object"},"summary":{"description":"Overall totals (all-time current state, not filtered by date range). Represents the Financial Snapshot section. Scoped to the active tab: type=invoicing returns Invoice + Pro Forma cards, type=payments returns Payable + Payment Statement cards. Includes every status for the tab (isDefault=true are the always-visible cards; isDefault=false are the extra cards surfaced by the 'view all statuses' checkboxes).","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"code":{"description":"Stable identifier for the card; matches the underlying financial_statuses.code where one exists, otherwise a synthetic rollup code.","type":"string","example":"INVOICE_OUTSTANDING"},"amount":{"type":"string","example":"$400"},"label":{"type":"string","example":"Outstanding"},"isDefault":{"description":"True for the always-visible snapshot cards; false for cards only shown once the user checks 'view all statuses'.","type":"boolean","example":true},"group":{"description":"Document type the card belongs to: invoice, proforma, payable, or payment_statement.","type":"string","example":"invoice"},"bgClass":{"type":"string","example":"bg-[var(--mui-palette-primary-main)]"},"color":{"type":"string","example":"var(--mui-palette-primary-main)"}},"type":"object"}},"periodSummary":{"description":"Same card set as 'summary', but each amount is scoped to the selected period/date range (by issue_date) instead of all-time.","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"code":{"type":"string","example":"INVOICE_OUTSTANDING"},"amount":{"type":"string","example":"$200"},"label":{"type":"string","example":"Outstanding"},"isDefault":{"type":"boolean","example":true},"group":{"type":"string","example":"invoice"},"bgClass":{"type":"string","example":"bg-[var(--mui-palette-primary-main)]"},"color":{"type":"string","example":"var(--mui-palette-primary-main)"}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":[],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/payable/calculation-method":{"post":{"tags":["Finances"],"summary":"Get per-entity payable pay calculation metrics","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nReturns pay calculation metrics for each billable assignment/shift in one batch: pay_time_basis, hours_used_for_pay, pay_rate, services_charge, and optional warning_message per entity.","operationId":"ext_post_finance_payable_calculation_method","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["provider_id","billable_entities"],"properties":{"provider_id":{"description":"Provider user id","type":"string","example":"USR-PROVIDER-123"},"billable_entities":{"description":"Assignments/shifts with optional per-entity pay_time_basis and override fields for preview (override reasons not required).","type":"array","items":{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"type":"string","enum":["scheduled_time","actual_worked_time","scheduled_actual_fallback"]},"hours_used_for_pay":{"type":"number","format":"float","example":4,"nullable":true},"pay_rate":{"type":"number","format":"float","example":65,"nullable":true}},"type":"object"}},"pay_time_basis":{"description":"Optional document-level default when per-entity basis is omitted.","type":"string","enum":["scheduled_time","actual_worked_time","scheduled_actual_fallback"],"nullable":true},"payable_id":{"description":"When editing an existing payable, uses the stored pay metrics for work items the request does not override.","type":"string","example":"PAY-1001","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Payable calculation method metrics fetched successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable calculation method metrics fetched successfully."},"data":{"required":["entities"],"properties":{"entities":{"type":"array","items":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"type":"string","example":"scheduled_actual_fallback"},"derived_hours_used_for_pay":{"type":"number","format":"float","example":8},"hours_used_for_pay":{"type":"number","format":"float","example":8},"is_hours_overridden":{"type":"boolean","example":false},"derived_pay_rate":{"type":"number","format":"float","example":45},"pay_rate":{"type":"number","format":"float","example":45},"is_pay_rate_overridden":{"type":"boolean","example":false},"services_charge":{"type":"number","format":"float","example":260},"pay_rate_breakdown":{"properties":{"base_rate":{"type":"number","format":"float","example":45},"base_hours":{"type":"number","format":"float","example":8},"rules_applied":{"type":"array","items":{"type":"object"}},"rate_lines":{"type":"array","items":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}},"summary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"effective_pay_rate":{"type":"number","format":"float","example":46.67},"total_service_charge":{"type":"number","format":"float","example":360},"source":{"description":"Which time basis priced the lines — not where the rate came from; see rate_source.","type":"string","enum":["check_in","estimated_pay"]},"rate_source":{"description":"Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"description":"Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.","type":"string","example":"Provider Pay Rate","nullable":true},"rate_source_description":{"type":"string","example":"Driven by this provider's own custom pay rate configuration.","nullable":true},"rate_source_is_mixed":{"description":"True when the lines were priced from more than one rate configuration.","type":"boolean","example":false},"rate_configuration":{"description":"Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows.","properties":{"source":{"description":"Null when the work item was priced from more than one configuration.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"label":{"type":"string","example":"Default Pay Rate","nullable":true},"description":{"type":"string","example":"Driven by the organization default provider pay rate configuration.","nullable":true},"is_mixed":{"type":"boolean","example":false},"rows":{"type":"array","items":{"properties":{"service_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"service_provider_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"rate_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"site_type":{"type":"string","example":"onsite_client","nullable":true},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","enum":["hr","min"],"example":"hr"},"source":{"type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"rate_rules_suppressed":{"type":"boolean","example":false},"warning_message":{"type":"string","nullable":true},"hours_override_reason":{"type":"string","nullable":true},"pay_rate_override_reason":{"type":"string","nullable":true}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Failed to calculate payable metrics","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/payables":{"get":{"tags":["Finances"],"summary":"Retrieve a list of payables","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of payables based on search criteria, filters, and sorting options.","operationId":"ext_get_finance_payables","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter payables by payable number, provider name, or email.","required":false,"schema":{"type":"string","example":"PAY-001"}},{"name":"status","in":"query","description":"Filter payables by status.","required":false,"schema":{"type":"string","enum":["draft","approved","partially_paid","paid","canceled"],"example":"paid"}},{"name":"providerId","in":"query","description":"Filter payables by provider ID.","required":false,"schema":{"type":"string","example":"USR-12345"}},{"name":"startDate","in":"query","description":"Filter payables created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter payables created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort payables by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of payables to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"type","in":"query","description":"Filter payables by document generation type (manual or system_generated). Same as payableType; takes precedence if both are sent.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"payableType","in":"query","description":"Filter by manual vs system_generated (enum value or label). Ignored if type is set.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"isPublished","in":"query","description":"Filter by the Publication Status column: true for published, false for drafts.","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"Payables retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"number","example":0},"paid_label":{"type":"string","example":"Paid in payable","nullable":true},"provider":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"paymentTerms":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"value":{"type":"string","nullable":true}},"type":"object","nullable":true},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"dueDate":{"type":"string","example":"2026-01-15","nullable":true},"approvedAt":{"type":"string","example":"2026-01-15 09:00:00","nullable":true},"approvalDate":{"type":"string","example":"2026-01-15","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"paidAmount":{"type":"number","example":0},"balanceDue":{"type":"number","example":0},"assignmentIds":{"type":"array","items":[],"nullable":true},"shiftIds":{"type":"array","items":[],"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1},"post":{"tags":["Finances"],"summary":"Create or update a payable","description":"**Required scope:** `finance:write`  \n**Roles:** admin, scheduler\n\nCreates or updates a payable. Work items (assignments/shifts) already paid to this provider are excluded from services_charges. When duplicating (source_document_id), if the source is paid, amounts are zeroed.","operationId":"ext_post_finance_payables","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["provider_id"],"properties":{"override_locks":{"description":"Edit a paid document past its locks. Send on the retry after a save asks.","type":"boolean","nullable":true},"override_reason":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"nullable":true},"confirmation":{"description":"Confirms the resend prompt a save on a sent document raises.","type":"boolean","nullable":true},"resend_delivery":{"type":"string","enum":["send_updated","internal_only","send_now","save_only"],"nullable":true},"overpayment_confirmation":{"description":"Accept a payment that exceeds the balance due.","type":"boolean","nullable":true},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"nullable":true},"internalNotes":{"type":"string","maxLength":2000,"minLength":2,"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"id":{"description":"Payable ID (include for update, omit for create)","type":"string","example":"PAY-ABC123"},"source_document_id":{"description":"Optional. Source document ID for duplication. If provided and source is paid (status Paid or balance_due <= 0), amounts are zeroed unless full_copy=true.","type":"string","example":"PAY-ABC123"},"full_copy":{"description":"When true, skip paid-source zeroing and keep full charges.","type":"boolean","example":true},"provider_id":{"description":"Provider selection","properties":{"id":{"description":"Provider ID","type":"string","example":"USR-12345"},"label":{"description":"Provider name","type":"string","example":"John Doe"}},"type":"object"},"billable_entities":{"description":"Work items linked to this payable (assignment/shift ids only). Required when published.","type":"array","items":{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"}},"type":"object"}},"billable_entities_pay_calc":{"description":"Per-entity pay calculation inputs. Required when published. Override reasons required on save when hours/rate differ from derived.","type":"array","items":{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"type":"string","enum":["scheduled_time","actual_worked_time","scheduled_actual_fallback"],"nullable":true},"hours_used_for_pay":{"type":"number","format":"float","example":4,"nullable":true},"pay_rate":{"type":"number","format":"float","example":65,"nullable":true},"services_charge":{"type":"number","format":"float","example":260,"nullable":true},"hours_override_reason":{"type":"string","minLength":3,"nullable":true},"pay_rate_override_reason":{"type":"string","minLength":3,"nullable":true}},"type":"object"}},"line_items":{"description":"Array of line items","type":"array","items":{"required":["amount","type"],"properties":{"name":{"description":"Line item name (optional)","type":"string","example":"Shift Pay"},"description":{"description":"Line item description (optional)","type":"string","example":"Shift payment"},"amount":{"description":"Line item amount","type":"number","format":"float","example":100},"type":{"description":"Line item type","properties":{"id":{"description":"Line item type ID","type":"string","example":"shift_pay"},"label":{"description":"Line item type label","type":"string","example":"Shift Payment"}},"type":"object"}},"type":"object"}},"summary":{"description":"Tax, discount and payments on a finance document. A type needs its amount alongside it.","properties":{"tax_type":{"properties":{"id":{"type":"string","enum":["Fixed","Percentage"],"example":"Percentage"},"label":{"type":"string","example":"Percentage"}},"type":"object","nullable":true},"tax_amount":{"type":"number","minimum":0,"example":8.25,"nullable":true},"discount_type":{"properties":{"id":{"type":"string","enum":["Fixed","Percentage"],"example":"Fixed"},"label":{"type":"string","example":"Fixed"}},"type":"object","nullable":true},"discount_amount":{"type":"number","minimum":0,"example":10,"nullable":true},"payments_applied":{"type":"number","minimum":0,"nullable":true}},"type":"object"},"status":{"description":"Payable status","properties":{"id":{"description":"Status ID","type":"integer","example":1},"label":{"description":"Status label","type":"string","example":"Sent"}},"type":"object"},"payment_terms":{"description":"Payment terms","properties":{"id":{"description":"Payment terms ID","type":"integer","example":1},"label":{"description":"Payment terms label","type":"string","example":"Net 15"}},"type":"object"},"issue_date":{"description":"Payable issue date","type":"string","format":"date","example":"2025-01-01"},"notes":{"description":"Payable notes","type":"string","example":"Payment due within 15 days."},"documents":{"description":"Array of documents to attach","type":"array","items":{"properties":{"id":{"description":"Document ID (for updates)","type":"integer","example":1},"file":{"description":"File to upload","type":"string","format":"binary"},"fileName":{"description":"Document file name","type":"string","example":"assignment2.png"},"isPublic":{"description":"Whether document is public","type":"boolean","example":true},"categories":{"description":"Document categories","type":"array","items":{"properties":{"id":{"description":"Category ID","type":"integer","example":1},"label":{"description":"Category name","type":"string","example":"Supporting Docs"}},"type":"object"}},"tags":{"description":"Document tags","type":"array","items":{"properties":{"id":{"description":"Tag ID","type":"string","example":"tag-1"},"label":{"description":"Tag name","type":"string","example":"Internal Use"}},"type":"object"}}},"type":"object"}},"is_published":{"description":"Whether the payable is published","type":"boolean","example":true}},"type":"object"}}}},"responses":{"200":{"description":"Payable updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable updated successfully."},"data":{"properties":{"id":{"type":"string","example":"PAY-ABC123"}},"type":"object"}},"type":"object"}}}},"201":{"description":"Payable created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable created successfully."},"data":{"properties":{"id":{"type":"string","example":"PAY-ABC123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"provider_id":["Provider is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Payable operation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/payables-details":{"get":{"tags":["Finances"],"summary":"Get detailed information for multiple payables","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves comprehensive details for multiple payables including provider information, assignments, shifts, financial summary, and line items. Used for selecting payables to include in payment statements.","operationId":"ext_get_finance_payables_details","parameters":[{"name":"ids","in":"query","description":"Comma-separated list of Payable IDs to get details for","required":true,"schema":{"type":"string","example":"PAYB-12345,PAYB-67890"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Payable details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable details retrieved successfully"},"data":{"type":"array","items":{"properties":{"id":{"description":"Payable id for list selection","type":"string","example":"PAYB-12345"},"selectedPayableSummary":{"description":"Expanded payable card, mirroring invoice selectedInvoiceSummary. Same item shape as payment statement selectedPayablesSummary: provider profile block (contact info + role), per-assignment/shift Service Breakdown with itemized expenses, financialSummary and paymentHistory.","properties":{"id":{"type":"string","example":"PAYB-12345"},"provider":{"properties":{"id":{"type":"string","example":"SP-12345"},"name":{"type":"string","example":"Archer Moon"},"email":{"type":"string","example":"amanda890@ideo.com"},"phone":{"type":"string","example":"(123) 456-7890"}},"type":"object"},"financialSummary":{"properties":{"totalPayableAmount":{"type":"number","format":"float","example":178.5}},"type":"object"},"status":{"type":"string","example":"Sent"},"total":{"type":"number","format":"float","example":178.5},"is_paid":{"description":"True if this payable is paid (status PAYABLE_PAID or balance_due <= 0 and paid_amount > 0). Exclude it from the payment statement total and charges.","type":"boolean","example":false},"paid_label":{"description":"'Paid in payable' when is_paid is true; null otherwise.","type":"string","example":null,"nullable":true}},"type":"object"}},"type":"object"}}},"type":"object"}}}},"400":{"description":"Missing required parameter","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Missing required parameter: ids"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/payables/by-provider/{provider_id}":{"get":{"tags":["Finances"],"summary":"Retrieve payables by provider ID","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches all matching payables for a specific provider with filtering and sorting options (no pagination).","operationId":"ext_get_finance_payables_by_provider_By_provider_id","parameters":[{"name":"provider_id","in":"path","description":"Provider ID","required":true,"schema":{"type":"string","example":"USR-12345"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Payables retrieved successfully (non-paginated list)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payables retrieved successfully."},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"number","example":0},"paid_label":{"type":"string","example":"Paid in payable","nullable":true},"provider":{"properties":{"id":{"type":"string"},"name":{"type":"string","example":"Example name"},"email":{"type":"string","example":"user@example.com"},"logo":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"}},"type":"object","nullable":true},"paymentTerms":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"value":{"type":"string","nullable":true}},"type":"object","nullable":true},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"dueDate":{"type":"string","example":"2026-01-15","nullable":true},"approvedAt":{"type":"string","example":"2026-01-15 09:00:00","nullable":true},"approvalDate":{"type":"string","example":"2026-01-15","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"paidAmount":{"type":"number","example":0},"balanceDue":{"type":"number","example":0},"assignmentIds":{"type":"array","items":[],"nullable":true},"shiftIds":{"type":"array","items":[],"nullable":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Provider not found or no payables found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"No payables found for this provider."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/payables/{id}":{"put":{"tags":["Finances"],"summary":"Update payable inline fields","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdate specific payable fields (financial status) for inline editing.","operationId":"ext_put_finance_payables_By_id","parameters":[{"name":"id","in":"path","description":"Payable ID","required":true,"schema":{"type":"string","example":"PAYB-EWDM3W"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"override_locks":{"description":"Edit a paid document past its locks. Send on the retry after a save asks.","type":"boolean","nullable":true},"override_reason":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"nullable":true},"confirmation":{"description":"Confirms the resend prompt a save on a sent document raises.","type":"boolean","nullable":true},"resend_delivery":{"type":"string","enum":["send_updated","internal_only","send_now","save_only"],"nullable":true},"overpayment_confirmation":{"description":"Accept a payment that exceeds the balance due.","type":"boolean","nullable":true},"payment_terms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Net 15"},"isCustom":{"type":"boolean","example":false,"nullable":true}},"type":"object","nullable":true},"payment_amount":{"description":"Records a payment against the payable.","type":"number","minimum":0,"exclusiveMinimum":true,"example":120,"nullable":true},"payment_method":{"type":"string","maxLength":50,"example":"ach","nullable":true},"transaction_id":{"type":"string","maxLength":255,"nullable":true},"reason":{"description":"Why the status changed.","type":"string","maxLength":500,"nullable":true},"status":{"description":"Financial status to update","properties":{"id":{"description":"Financial status ID","type":"integer","example":4},"label":{"description":"Financial status label","type":"string","example":"Paid"},"isCustom":{"description":"Whether status is custom","type":"boolean","example":false}},"type":"object","nullable":true},"is_published":{"description":"Whether the payable is published (inline toggle)","type":"boolean","example":false}},"type":"object"}}}},"responses":{"200":{"description":"Payable updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable updated successfully."},"data":{"properties":{"id":{"type":"string","example":"PAYB-EWDM3W"},"status":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Approved"}},"type":"object"},"is_published":{"description":"Whether the payable is published","type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payable not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payable not found."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"status":["Status is invalid."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Payable update failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/payables/{id}/review":{"post":{"tags":["Finances"],"summary":"Review a payable","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nMarks a payable as reviewed (status Prepared → Reviewed). Required when 'Require Payable Review' is ON before the payable can be approved.","operationId":"ext_post_finance_payables_By_id_review","parameters":[{"name":"id","in":"path","description":"Payable ID","required":true,"schema":{"type":"string","example":"PAYB-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Payable marked as reviewed successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable marked as reviewed successfully."},"data":{"properties":{"payable_id":{"type":"string","example":"PAYB-ABC123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden – only admins or schedulers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payable not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"Payable is not in Prepared status","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/payables/{payable}":{"delete":{"tags":["Finances"],"summary":"Delete a payable","operationId":"ext_delete_finance_payables_By_payable","parameters":[{"name":"payable","in":"path","description":"Payable ID","required":true,"schema":{"type":"string","example":"PAY-A0XJRY"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Payable deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payable not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payable not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Payable deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:delete","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `finance:delete`  \n**Roles:** admin, scheduler","x-fido-area":"Payables","x-fido-area-rank":1},"get":{"tags":["Finances"],"summary":"Retrieve a specific payable","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches detailed information about a specific payable including line items, billable_entities (linkage), billable_entities_pay_calc (per-entity pay metrics), compensation_summary, and attachments.","operationId":"ext_get_finance_payables_By_payable","parameters":[{"name":"payable","in":"path","description":"Payable ID","required":true,"schema":{"type":"string","example":"PAY-A0XJRY"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"for_duplicate","in":"query","description":"If true, automatically zero amounts if the payable is paid (for duplication purposes)","required":false,"schema":{"type":"boolean","example":false}}],"responses":{"200":{"description":"Payable retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payable retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"id":{"type":"string","example":"PAY-ABC123"},"provider":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"status":{"type":"string","example":"paid"},"issueDate":{"type":"string","format":"date","example":"2025-01-01"},"approvalDate":{"type":"string","format":"date","example":"2025-01-15"},"subtotal":{"type":"number","format":"float","example":150},"taxAmount":{"type":"number","format":"float","example":15},"taxPercentage":{"type":"number","format":"float","example":10},"discountAmount":{"type":"number","format":"float","example":10},"total":{"type":"number","format":"float","example":160},"paidAmount":{"type":"number","format":"float","example":160},"balanceDue":{"type":"number","format":"float","example":0},"notes":{"type":"string","example":"Approved for provider payout"},"paymentAcknowledgedAt":{"description":"Formatted like issue_date/paid_at via presentation settings (admin: Y-m-d H:i:s; portal: org date format).","type":"string","example":"2026-07-31 12:00:00","nullable":true},"paymentAcknowledgedBy":{"properties":{"id":{"type":"string","example":"USR-12345"},"name":{"type":"string","example":"John Provider"},"image":{"type":"string","example":null,"nullable":true}},"type":"object","nullable":true},"lineItems":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"title":{"type":"string","example":"Shift Payment"},"description":{"type":"string","example":"Payment for shift work"},"quantity":{"type":"number","format":"float","example":1},"unitPrice":{"type":"number","format":"float","example":150},"total":{"type":"number","format":"float","example":150}},"type":"object"}},"billable_entities":{"type":"array","items":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"is_deleted":{"type":"boolean","example":false}},"type":"object"}},"billable_entities_pay_calc":{"type":"array","items":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"isCustom":{"type":"boolean","example":false}},"type":"object","nullable":true},"derived_hours_used_for_pay":{"type":"number","format":"float","nullable":true},"hours_used_for_pay":{"type":"number","format":"float","nullable":true},"is_hours_overridden":{"type":"boolean","example":false},"derived_pay_rate":{"type":"number","format":"float","nullable":true},"pay_rate":{"type":"number","format":"float","nullable":true},"is_pay_rate_overridden":{"type":"boolean","example":false},"services_charge":{"type":"number","format":"float","nullable":true},"pay_rate_breakdown":{"properties":{"base_rate":{"type":"number","format":"float","example":45},"base_hours":{"type":"number","format":"float","example":8},"rules_applied":{"type":"array","items":{"type":"object"}},"rate_lines":{"type":"array","items":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}},"summary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"effective_pay_rate":{"type":"number","format":"float","example":46.67},"total_service_charge":{"type":"number","format":"float","example":360},"source":{"description":"Which time basis priced the lines — not where the rate came from; see rate_source.","type":"string","enum":["check_in","estimated_pay"]},"rate_source":{"description":"Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"description":"Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.","type":"string","example":"Provider Pay Rate","nullable":true},"rate_source_description":{"type":"string","example":"Driven by this provider's own custom pay rate configuration.","nullable":true},"rate_source_is_mixed":{"description":"True when the lines were priced from more than one rate configuration.","type":"boolean","example":false},"rate_configuration":{"description":"Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows.","properties":{"source":{"description":"Null when the work item was priced from more than one configuration.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"label":{"type":"string","example":"Default Pay Rate","nullable":true},"description":{"type":"string","example":"Driven by the organization default provider pay rate configuration.","nullable":true},"is_mixed":{"type":"boolean","example":false},"rows":{"type":"array","items":{"properties":{"service_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"service_provider_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"rate_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"site_type":{"type":"string","example":"onsite_client","nullable":true},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","enum":["hr","min"],"example":"hr"},"source":{"type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"rate_rules_suppressed":{"type":"boolean","example":false},"hours_override_reason":{"description":"Latest hours override reason (mirrors save input when is_hours_overridden).","type":"string","nullable":true},"pay_rate_override_reason":{"description":"Latest pay rate override reason (mirrors save input when is_pay_rate_overridden).","type":"string","nullable":true}},"type":"object"}},"compensation_summary":{"properties":{"workitems":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-12345"},"name":{"type":"string","example":"Assignment Title"},"type":{"type":"string","example":"assignment"},"pay_time_basis":{"type":"string","example":"scheduled_time","nullable":true},"hours_used_for_pay":{"type":"number","format":"float","example":4},"pay_rate":{"type":"number","format":"float","example":65},"services_charge":{"type":"number","format":"float","example":260},"service_cost":{"type":"number","format":"float","example":260},"expenses_total":{"type":"number","format":"float","example":0},"total_payment":{"type":"number","format":"float","example":260}},"type":"object"}},"service_cost":{"type":"number","format":"float","example":260},"expenses_total":{"type":"number","format":"float","example":0},"total":{"type":"number","format":"float","example":260}},"type":"object"},"selectedPayableSummary":{"description":"Expanded payable card, mirroring invoice selectedInvoiceSummary. Same item shape as payment statement selectedPayablesSummary: provider profile block (contact info + role), per-assignment/shift Service Breakdown with itemized expenses, financialSummary and paymentHistory.","type":"object"},"attachments":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"fileName":{"type":"string","example":"payable.pdf"},"filePath":{"type":"string","example":"path/to/file"}},"type":"object"}},"billable_entities_billing":{"description":"Per work-item billing intent, with the adminFeeBreakdown stored for each work item.","type":"array","items":{"type":"object"}},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"paymentSection":{"description":"Present when the caller can pay or record a payment.","type":"object","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payable not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payable not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payables","x-fido-area-rank":1}},"/v1/finance/payment-statements":{"get":{"tags":["Finances"],"summary":"Retrieve a list of payment statements","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of payment statements based on search criteria, filters, and sorting options.","operationId":"ext_get_finance_payment_statements","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter payment statements by specified columns.","required":false,"schema":{"type":"string","example":"PS-001"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search in (e.g., 'paymentStatement,provider,status,total').","required":false,"schema":{"type":"string","example":"paymentStatement,provider"}},{"name":"status","in":"query","description":"Filter payment statements by status.","required":false,"schema":{"type":"string","enum":["generated","sent","confirmed","disputed","void"],"example":"sent"}},{"name":"providerId","in":"query","description":"Filter payment statements by provider ID.","required":false,"schema":{"type":"string","example":"SP-12345"}},{"name":"startDate","in":"query","description":"Filter payment statements created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter payment statements created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort payment statements by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of payment statements to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"type","in":"query","description":"Filter by document generation type (manual or system_generated). Same as paymentStatementType; takes precedence if both are sent.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"paymentStatementType","in":"query","description":"Filter by manual vs system_generated. Ignored if type is set.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"isPublished","in":"query","description":"Filter by the Publication Status column: true for published, false for drafts.","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"Payment statements retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"boolean","example":true},"paid_label":{"type":"string","example":"Paid in payment statement","nullable":true},"provider":{"properties":{"id":{"type":"string","example":"SP-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"paymentTerms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"expiryDate":{"type":"string","example":"2026-01-15","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"paidAmount":{"type":"string"},"balanceDue":{"type":"number","example":0},"payableIds":{"type":"array","items":[]},"assignmentIds":{"type":"array","items":[]},"shiftIds":{"type":"array","items":[]}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payment statements","x-fido-area-rank":5}},"/v1/finance/payment-statements/{id}":{"put":{"tags":["Finances"],"summary":"Update payment statement inline fields","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdate specific payment statement fields (financial status) for inline editing.","operationId":"ext_put_finance_payment_statements_By_id","parameters":[{"name":"id","in":"path","description":"Payment statement ID","required":true,"schema":{"type":"string","example":"PS-EWDM3W"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"override_locks":{"description":"Edit a paid document past its locks. Send on the retry after a save asks.","type":"boolean","nullable":true},"override_reason":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"nullable":true},"confirmation":{"description":"Confirms the resend prompt a save on a sent document raises.","type":"boolean","nullable":true},"resend_delivery":{"type":"string","enum":["send_updated","internal_only","send_now","save_only"],"nullable":true},"overpayment_confirmation":{"description":"Accept a payment that exceeds the balance due.","type":"boolean","nullable":true},"payment_terms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Net 15"},"isCustom":{"type":"boolean","example":false,"nullable":true}},"type":"object","nullable":true},"status":{"description":"Financial status to update","properties":{"id":{"description":"Financial status ID","type":"integer","example":4},"label":{"description":"Financial status label","type":"string","example":"Sent"},"isCustom":{"description":"Whether status is custom","type":"boolean","example":false}},"type":"object","nullable":true},"is_published":{"description":"Whether the payment statement is published (inline toggle)","type":"boolean","example":false}},"type":"object"}}}},"responses":{"200":{"description":"Payment statement updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payment statement updated successfully."},"data":{"properties":{"id":{"type":"string","example":"PS-EWDM3W"},"status":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Sent"}},"type":"object"},"is_published":{"description":"Whether the payment statement is published","type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payment statement not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payment statement not found."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"status":["Status is invalid."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Payment statement update failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payment statements","x-fido-area-rank":5}},"/v1/finance/payment-statements/{payment_statement}":{"delete":{"tags":["Finances"],"summary":"Delete a payment statement","operationId":"ext_delete_finance_payment_statements_By_payment_statement","parameters":[{"name":"payment_statement","in":"path","description":"Payment statement ID","required":true,"schema":{"type":"string","example":"PS-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Payment statement deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payment statement deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payment statement not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payment statement not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Payment statement deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:delete","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `finance:delete`  \n**Roles:** admin, scheduler","x-fido-area":"Payment statements","x-fido-area-rank":5},"get":{"tags":["Finances"],"summary":"Retrieve a specific payment statement","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches detailed information about a specific payment statement including line items and provider details.","operationId":"ext_get_finance_payment_statements_By_payment_statement","parameters":[{"name":"payment_statement","in":"path","description":"Payment statement ID","required":true,"schema":{"type":"string","example":"PS-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"for_duplicate","in":"query","description":"If true, automatically zero amounts if the payment statement is paid (for duplication purposes)","required":false,"schema":{"type":"boolean","example":false}}],"responses":{"200":{"description":"Payment statement retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payment statement retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"id":{"type":"integer","example":1},"paymentStatementNumber":{"type":"string","example":"PS-20250101-0001"},"provider":{"properties":{"id":{"type":"string","example":"SP-12345"},"name":{"type":"string","example":"John Doe"}},"type":"object"},"status":{"type":"string","example":"sent"},"issueDate":{"type":"string","format":"date","example":"2025-01-01"},"dueDate":{"type":"string","format":"date","example":"2025-01-15"},"total":{"type":"number","format":"float","example":150},"lineItems":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Reimbursement"},"amount":{"type":"number","format":"float","example":150},"type":{"type":"string","example":"reimbursement"}},"type":"object"}},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"billable_entities":{"description":"Linked assignments and shifts, with is_deleted when the work item was removed.","type":"array","items":{"type":"object"},"nullable":true},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"paymentSection":{"description":"Present when the caller can pay or record a payment.","type":"object","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Payment statement not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Payment statement not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Payment statements","x-fido-area-rank":5}},"/v1/finance/pro-formas":{"get":{"tags":["Finances"],"summary":"Retrieve a list of pro forma invoices","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of pro forma invoices based on search criteria, filters, and sorting options.","operationId":"ext_get_finance_pro_formas","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter pro formas by specified columns.","required":false,"schema":{"type":"string","example":"PRF-001"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search in (e.g., 'proForma,client,status,total').","required":false,"schema":{"type":"string","example":"proForma,client"}},{"name":"status","in":"query","description":"Filter pro formas by status.","required":false,"schema":{"type":"string","enum":["draft","sent","approved","rejected","converted"],"example":"sent"}},{"name":"clientId","in":"query","description":"Filter pro formas by client ID.","required":false,"schema":{"type":"string","example":"CLT-12345"}},{"name":"startDate","in":"query","description":"Filter pro formas created on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter pro formas created on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort pro formas by a specific field (e.g., 'created_at', 'total').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of pro formas to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"type","in":"query","description":"Filter by document generation type (manual or system_generated). Same as proformaType; takes precedence if both are sent.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"proformaType","in":"query","description":"Filter by manual vs system_generated. Ignored if type is set.","required":false,"schema":{"type":"string","enum":["manual","system_generated"],"example":"manual"}},{"name":"approvalStatus","in":"query","description":"Filter pro formas by internal approval status.","required":false,"schema":{"type":"string","enum":["pending","approved","rejected","cancelled"],"example":"pending"}},{"name":"isPublished","in":"query","description":"Filter by the Publication Status column: true for published, false for drafts.","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"Pro formas retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"is_paid":{"type":"boolean","example":true},"paid_label":{"type":"string","example":"Paid in pro forma","nullable":true},"client":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"}},"type":"object"},"issueDate":{"type":"string","example":"2026-01-15","nullable":true},"dueDate":{"type":"string","example":"2026-01-15","nullable":true},"paymentTerms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"taxPercentage":{"type":"number","example":0,"nullable":true},"discountAmount":{"type":"number","example":0},"subtotal":{"type":"number","example":0},"balanceDue":{"type":"number","example":0},"expiryDate":{"type":"string","example":"2026-01-15","nullable":true},"isExpired":{"type":"boolean","example":true},"invoiceIds":{"type":"array","items":[]},"assignmentIds":{"type":"array","items":[]},"shiftIds":{"type":"array","items":[]}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2},"post":{"tags":["Finances"],"summary":"Create or update a pro forma invoice","operationId":"ext_post_finance_pro_formas","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["client_id"],"properties":{"override_locks":{"description":"Edit a paid document past its locks. Send on the retry after a save asks.","type":"boolean","nullable":true},"override_reason":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"nullable":true},"confirmation":{"description":"Confirms the resend prompt a save on a sent document raises.","type":"boolean","nullable":true},"resend_delivery":{"type":"string","enum":["send_updated","internal_only","send_now","save_only"],"nullable":true},"overpayment_confirmation":{"description":"Accept a payment that exceeds the balance due.","type":"boolean","nullable":true},"payment_terms":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"expiry_date":{"description":"On or after issue_date. expiryDate is accepted as an alias.","type":"string","format":"date","example":"2025-02-15","nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"id":{"description":"Pro forma ID (include for update, omit for create)","type":"string","example":"PF-1IU6BD"},"source_document_id":{"description":"Optional source document ID for duplication. If provided and source is accepted, amounts will be automatically zeroed.","type":"string","example":"PF-ABC123"},"client_id":{"description":"Client selection","properties":{"id":{"description":"Client ID","type":"string","example":"CLT-N3B72G"},"label":{"description":"Client name","type":"string","example":"Test Client Company"}},"type":"object"},"billable_entities":{"description":"Invoices to include in the pro forma. Required when published.","type":"array","items":{"properties":{"type":{"description":"Entity type","type":"string","example":"invoice"},"id":{"description":"Entity ID","type":"string","example":"INV-QKPWQ9"}},"type":"object"}},"issue_date":{"description":"Issue date","type":"string","format":"date","example":"2025-01-15"},"due_date":{"description":"Due date","type":"string","format":"date","example":"2025-01-30"},"line_items":{"description":"Array of additional line items (optional)","type":"array","items":{"required":["amount","type"],"properties":{"name":{"description":"Line item name (optional)","type":"string","example":"Consultation Fee"},"description":{"description":"Line item description (optional)","type":"string","example":"Initial consultation service"},"amount":{"description":"Line item amount","type":"number","format":"float","example":150},"type":{"description":"Line item type","properties":{"id":{"description":"Line item type ID","type":"string","enum":["charges","credit","reimbursement"],"example":"charges"},"label":{"description":"Line item type label (optional)","type":"string","example":"Charges"}},"type":"object"}},"type":"object"}},"summary":{"description":"Pro forma summary with tax and discount details","properties":{"tax_type":{"description":"Tax type","properties":{"id":{"description":"Tax type ID","type":"string","enum":["Fixed","Percentage"],"example":"Percentage"},"label":{"description":"Tax type label","type":"string","example":"Percentage Tax"}},"type":"object"},"tax_amount":{"description":"Tax amount/percentage","type":"number","format":"float","example":15},"discount_type":{"description":"Discount type","properties":{"id":{"description":"Discount type ID","type":"string","enum":["Fixed","Percentage"],"example":"Fixed"},"label":{"description":"Discount type label","type":"string","example":"Fixed Discount"}},"type":"object"},"discount_amount":{"description":"Discount amount/percentage","type":"number","format":"float","example":10},"payments_applied":{"description":"Payments already applied","type":"number","format":"float","example":25}},"type":"object"},"status":{"description":"Pro forma status","properties":{"id":{"description":"Status ID","type":"integer","example":1},"label":{"description":"Status label","type":"string","example":"Sent"}},"type":"object"},"notes":{"description":"Pro forma notes","type":"string","example":"Payment due within 15 days."},"documents":{"description":"Array of documents to attach","type":"array","items":{"properties":{"id":{"description":"Document ID (for updates)","type":"integer","example":null},"file":{"description":"File to upload","type":"string","format":"binary"},"fileName":{"description":"Document file name","type":"string","example":"assignment2.png"},"isPublic":{"description":"Whether document is public","type":"boolean","example":true},"categories":{"description":"Document categories","type":"array","items":{"properties":{"id":{"description":"Category ID","type":"integer","example":null},"label":{"description":"Category name","type":"string","example":"Supporting Docs"}},"type":"object"}},"tags":{"description":"Document tags","type":"array","items":{"properties":{"id":{"description":"Tag ID","type":"string","example":null},"label":{"description":"Tag name","type":"string","example":"Internal Use23"}},"type":"object"}}},"type":"object"}},"is_published":{"description":"Whether the pro forma is published","type":"boolean","example":true},"internalNotes":{"description":"Internal notes","type":"string","example":"s23"}},"type":"object"}}}},"responses":{"200":{"description":"Pro forma updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma updated successfully."},"data":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"201":{"description":"Pro forma created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma created successfully."},"data":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"client_id":["Client is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Pro forma operation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `finance:write`  \n**Roles:** admin, scheduler","x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/pro-formas/by-client/{client_id}":{"get":{"tags":["Finances"],"summary":"Retrieve pro formas by client ID","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of pro formas for a specific client with filtering and sorting options.","operationId":"ext_get_finance_pro_formas_by_client_By_client_id","parameters":[{"name":"client_id","in":"path","description":"Client ID","required":true,"schema":{"type":"string","example":"CLT-12345"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"search","in":"query","description":"Search query to filter pro formas","required":false,"schema":{"type":"string","example":"PF-001"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search in","required":false,"schema":{"type":"string","example":"proForma,client"}},{"name":"statusId","in":"query","description":"Filter by status ID","required":false,"schema":{"type":"integer","example":1}},{"name":"startDate","in":"query","description":"Filter from this date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter until this date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Sort by field","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Pro formas retrieved successfully.","content":{"application/json":{"schema":{"description":"A paginated list. The envelope carries no message key on this endpoint.","properties":{"success":{"type":"boolean","example":true},"data":{"description":"Pro forma rows, the same shape the pro forma list returns.","type":"array","items":{"properties":{"id":{"type":"string","example":"PF-1IU6BD"},"is_paid":{"type":"boolean","example":false},"paid_label":{"type":"string","nullable":true},"client":{"properties":{"id":{"type":"string","example":"CLT-N3B72G"},"name":{"type":"string","example":"Example label"},"email":{"type":"string","nullable":true},"logo":{"type":"string","nullable":true},"onlineStatus":{"type":"string","nullable":true}},"type":"object"},"issueDate":{"type":"string","example":"01/15/2025","nullable":true},"dueDate":{"type":"string","example":"01/30/2025","nullable":true},"expiryDate":{"type":"string","example":"02/15/2025","nullable":true},"isExpired":{"type":"boolean","example":false},"paymentTerms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object"},"taxPercentage":{"type":"number","format":"float","example":8.25,"nullable":true},"discountAmount":{"type":"number","format":"float","example":0,"nullable":true},"subtotal":{"type":"number","format":"float","example":1250.5},"balanceDue":{"type":"number","format":"float","example":1250.5},"portal_accessible":{"type":"boolean","example":true},"invoiceIds":{"type":"array","items":{"properties":{"id":{"type":"string","example":"INV-QKPWQ9"}},"type":"object"}},"assignmentIds":{"type":"array","items":{"type":"string","example":"ASG-SA2IVL"}},"shiftIds":{"type":"array","items":{"type":"string","example":"SFT-9D2KQ1"}}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":4},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":37}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/pro-formas/{id}":{"put":{"tags":["Finances"],"summary":"Update pro forma inline fields","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdate specific pro forma fields (financial status) for inline editing.","operationId":"ext_put_finance_pro_formas_By_id","parameters":[{"name":"id","in":"path","description":"Pro forma ID","required":true,"schema":{"type":"string","example":"PF-EWDM3W"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"override_locks":{"description":"Edit a paid document past its locks. Send on the retry after a save asks.","type":"boolean","nullable":true},"override_reason":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"nullable":true},"confirmation":{"description":"Confirms the resend prompt a save on a sent document raises.","type":"boolean","nullable":true},"resend_delivery":{"type":"string","enum":["send_updated","internal_only","send_now","save_only"],"nullable":true},"overpayment_confirmation":{"description":"Accept a payment that exceeds the balance due.","type":"boolean","nullable":true},"payment_terms":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Net 15"},"isCustom":{"type":"boolean","example":false,"nullable":true}},"type":"object","nullable":true},"due_date":{"description":"dueDate is accepted as an alias.","type":"string","format":"date"},"expiry_date":{"description":"expiryDate is accepted as an alias.","type":"string","format":"date"},"rejection_reason":{"type":"string","maxLength":500,"nullable":true},"status":{"description":"Financial status to update","properties":{"id":{"description":"Financial status ID","type":"integer","example":4},"label":{"description":"Financial status label","type":"string","example":"Sent"},"isCustom":{"description":"Whether status is custom","type":"boolean","example":false}},"type":"object","nullable":true},"is_published":{"description":"Whether the pro forma is published (inline toggle)","type":"boolean","example":false}},"type":"object"}}}},"responses":{"200":{"description":"Pro forma updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma updated successfully."},"data":{"properties":{"id":{"type":"string","example":"PF-EWDM3W"},"status":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Sent"}},"type":"object"},"is_published":{"description":"Whether the pro forma is published","type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Pro forma not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Pro forma not found."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"status":["Status is invalid."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Pro forma update failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/pro-formas/{id}/convert-to-invoice":{"post":{"tags":["Finances"],"summary":"Convert accepted pro forma to invoice","description":"**Required scope:** `finance:write`  \n**Roles:** admin, scheduler\n\nConverts an accepted pro forma invoice into a regular invoice. Requires proforma to be in PROFORMA_ACCEPTED status and not already converted.","operationId":"ext_post_finance_pro_formas_By_id_convert_to_invoice","parameters":[{"name":"id","in":"path","description":"Pro forma ID","required":true,"schema":{"type":"string","example":"PF-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Pro forma converted to invoice successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma converted to invoice successfully."},"data":{"properties":{"invoice_id":{"description":"ID of the converted invoice (reused or newly created)","type":"string","example":"INV-ABC123"},"pro_forma_id":{"type":"string","example":"PF-ABC123"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid pro forma status or already converted","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"description":"Possible messages: 'Only accepted pro formas can be converted to invoices.' or 'This pro forma has already been converted to an invoice.'","type":"string","example":"Only accepted pro formas can be converted to invoices."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Pro forma not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Pro forma not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Conversion failed","nullable":true},"message":{"type":"string","example":"Unable to convert pro forma to invoice. Please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/pro-formas/{id}/payments":{"get":{"tags":["Finances"],"summary":"List pro forma payments","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nReturns payment history and allocation records for a pro forma.","operationId":"ext_get_finance_pro_formas_By_id_payments","parameters":[{"name":"id","in":"path","description":"Pro forma ID","required":true,"schema":{"type":"string","example":"PF-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Pro forma payments retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma payments retrieved successfully."},"data":{"description":"Payments against this pro forma, newest first. Model rows, so the keys are snake_case.","type":"array","items":{"properties":{"id":{"type":"integer","example":42},"pro_forma_id":{"type":"string","example":"PF-1IU6BD"},"client_id":{"type":"string","example":"CLT-N3B72G"},"amount":{"description":"Cast to two decimal places.","type":"string","example":"250.00"},"payment_method":{"type":"string","example":"manual"},"transaction_id":{"type":"string","example":"txn_1A2B3C","nullable":true},"payment_date":{"type":"string","format":"date","example":"2025-01-20"},"status":{"type":"string","example":"completed"},"notes":{"type":"string","nullable":true},"created_by":{"type":"string","example":"USR-9WE3TK","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true},"allocations":{"description":"How the payment was spread over the pro forma's invoices.","type":"array","items":{"properties":{"id":{"type":"integer","example":91},"pro_forma_payment_id":{"type":"integer","example":42},"invoice_id":{"type":"string","example":"INV-QKPWQ9"},"allocated_amount":{"type":"string","example":"250.00"},"allocation_source":{"type":"string","enum":["payment","credit"],"example":"payment"},"invoice":{"description":"The allocated invoice, eager-loaded.","type":"object","nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unable to retrieve payment history","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/pro-formas/{pro_forma}":{"delete":{"tags":["Finances"],"summary":"Delete a pro forma invoice","operationId":"ext_delete_finance_pro_formas_By_pro_forma","parameters":[{"name":"pro_forma","in":"path","description":"Pro forma ID","required":true,"schema":{"type":"string","example":"PF-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Pro forma deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Pro forma not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Pro forma not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Pro forma deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:delete","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `finance:delete`  \n**Roles:** admin, scheduler","x-fido-area":"Pro formas","x-fido-area-rank":2},"get":{"tags":["Finances"],"summary":"Retrieve a specific pro forma invoice","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nFetches detailed information about a specific pro forma including line items and client details.","operationId":"ext_get_finance_pro_formas_By_pro_forma","parameters":[{"name":"pro_forma","in":"path","description":"Pro forma ID","required":true,"schema":{"type":"string","example":"PF-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"for_duplicate","in":"query","description":"If true, automatically zero amounts if the pro forma is accepted (for duplication purposes)","required":false,"schema":{"type":"boolean","example":false}}],"responses":{"200":{"description":"Pro forma retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Pro forma retrieved successfully."},"data":{"description":"Fields every finance document detail shares. Each document type adds its own party and summary fields on top. Some keys appear only for some types or roles, as noted; portal callers (client, consumer, provider) never see internalNotes.","properties":{"id":{"type":"integer","example":1},"proFormaNumber":{"type":"string","example":"PRF-20250101-0001"},"client":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"John Doe"}},"type":"object"},"status":{"type":"string","example":"sent"},"issueDate":{"type":"string","format":"date","example":"2025-01-01"},"dueDate":{"type":"string","format":"date","example":"2025-01-15"},"total":{"type":"number","format":"float","example":150},"receiptAcknowledgedAt":{"description":"Formatted like issue_date/paid_at via presentation settings (admin: Y-m-d H:i:s; portal: org date format).","type":"string","example":"2026-07-31 12:00:00","nullable":true},"receiptAcknowledgedBy":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"Jane Client"},"image":{"type":"string","example":null,"nullable":true}},"type":"object","nullable":true},"paymentSection":{"description":"Client list/detail: present when actions includes initiate_payment (absent otherwise).","properties":{"mode":{"type":"string","enum":["external_url","custom_instructions"],"example":"external_url"},"externalUrl":{"type":"string","example":"https://pay.example/PF-1","nullable":true},"instructionsHtml":{"type":"string","nullable":true},"label":{"type":"string","example":"Payment"}},"type":"object","nullable":true},"lineItems":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Service Fee"},"amount":{"type":"number","format":"float","example":150},"type":{"type":"string","example":"charges"}},"type":"object"}},"currency":{"properties":{"code":{"type":"string","example":"USD"},"symbol":{"type":"string","example":"$"},"label":{"type":"string","example":"US Dollar"}},"type":"object"},"line_items":{"type":"array","items":{"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"type":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"summary":{"description":"Totals for display: services and expense charges, tax, discount, payments applied, total and balance due. Admin and scheduler callers get the internal breakdown as well.","type":"object"},"payment_terms":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"issue_date":{"type":"string","example":"2025-01-15","nullable":true},"due_date":{"description":"Null on an organization summary invoice.","type":"string","example":"2025-01-30","nullable":true},"expiry_date":{"description":"Pro formas and payment statements only.","type":"string","nullable":true},"is_expired":{"description":"Pro formas only.","type":"boolean","nullable":true},"paid_at":{"type":"string","example":"2025-01-20 14:05:00","nullable":true},"updatedAt":{"description":"In the organization's date and time format.","type":"string","nullable":true},"correctedAt":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"internalNotes":{"description":"Staff only.","type":"string","nullable":true},"is_published":{"type":"boolean"},"actions":{"description":"Actions the caller may take on this document now, such as send, mark_paid, void, download or send_message.","type":"array","items":{"type":"string"}},"documents":{"description":"Attached files.","type":"object","nullable":true},"refunds":{"description":"Invoices only.","type":"array","items":{"type":"object"}},"billable_entities":{"description":"Linked assignments and shifts, with is_deleted when the work item was removed.","type":"array","items":{"type":"object"},"nullable":true},"billable_entities_billing":{"type":"array","items":{"description":"How one linked work item is billed on this document. `bill` (default) pulls its service charges through; `reference` links it for record-keeping only, with expenses and the admin fee still billable through their own flags.","required":["id"],"properties":{"id":{"description":"A work item listed in billable_entities.","type":"string","example":"ASG-YZXCIT"},"billing_mode":{"type":"string","enum":["bill","reference"],"example":"bill","nullable":true},"bill_service":{"type":"boolean","nullable":true},"bill_expenses":{"type":"boolean","example":true,"nullable":true},"bill_admin_fee":{"type":"boolean","example":true,"nullable":true},"adminFeeBreakdown":{"properties":{"feeSource":{"type":"string","enum":["calculated","manual"],"nullable":true},"clients":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true},"providers":{"type":"array","items":{"properties":{"id":{"description":"Client or provider user id.","type":"string","example":"CLT-N3B72G","nullable":true},"feeSource":{"description":"Providers only.","type":"string","enum":["calculated","manual"],"nullable":true},"method":{"type":"string","enum":["flat","percentage"],"nullable":true},"value":{"type":"number","minimum":0,"example":5,"nullable":true},"source":{"description":"Clients only: where the fee was resolved from.","type":"string","enum":["client","client_location","organization","organization_location","tenant","default","none","work_item_ssot","invoice_client_scope","stored_estimate"],"nullable":true}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"}},"attempts":{"description":"Delivery and payment attempts on the document.","type":"array","items":{"type":"object"}},"customFields":{"type":"object","nullable":true},"payment_rollup":{"description":"Pro formas and payment statements: Unpaid, Partially Paid or Paid, with the amounts behind it.","type":"object","nullable":true},"approvalStatus":{"description":"Invoices and pro formas, staff only.","type":"string","nullable":true},"approvedBy":{"description":"Invoices and pro formas, staff only.","type":"object","nullable":true},"approvedAt":{"type":"string","nullable":true},"approvalDeadlineAt":{"type":"string","nullable":true},"requiresApproval":{"type":"boolean","nullable":true},"rejectionReason":{"description":"Rejected pro formas only.","type":"string","nullable":true},"terminal_reason_code":{"description":"Why a canceled or void document ended.","type":"string","nullable":true},"terminal_reason":{"type":"string","nullable":true},"reversed_from_paid_at":{"description":"Invoices only.","type":"string","nullable":true},"reverse_reason_code":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"reverse_reason":{"description":"Invoices only.","type":"string","nullable":true},"reverse_payment_handling":{"description":"Invoices only.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"fieldIsLocked":{"description":"Per field: {disabled, reason, sensitive}. Drives which fields an edit may change.","type":"object"},"canOverrideLocks":{"type":"boolean"},"overrideLocksApplied":{"description":"True when the request sent override_locks=true and the caller may override.","type":"boolean"},"promptResendOnSave":{"description":"A save should ask whether to resend the document.","type":"boolean"},"overpaymentGuard":{"type":"boolean"},"hasOverpayment":{"type":"boolean"},"overpaymentAmount":{"type":"number","nullable":true},"is_corrected":{"type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Pro forma not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Pro forma not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Pro formas","x-fido-area-rank":2}},"/v1/finance/provider-expenses":{"post":{"tags":["Finances"],"summary":"Store or update provider expenses","description":"**Required scope:** `finance:write`  \n**Roles:** admin, scheduler\n\nAllows providers or admin/scheduler to submit provider expenses for assignments or shifts. Template rows: for percentage, send amount or expense as submitted receipt (required); optional expense with amount is payout override. For per_unit/per_day/flat, send quantity and/or expense (line total override). maximumReimbursementCap: percentage caps receipt (422 if over); other bases cap line total (422 on explicit override, clamp on calculated). Custom rows (customName): expense amount required.","operationId":"ext_post_finance_provider_expenses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"required":["expenses"],"properties":{"affectFinancials":{"description":"Required when the change moves money on a work item whose linked finance document is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the change to those documents; false saves it and marks them out of sync.","type":"boolean","nullable":true},"expenses":{"type":"array","items":{"required":["assignmentId","serviceProviderId"],"properties":{"expense":{"description":"Non-percentage: reimbursement line total or override. Percentage: receipt when amount omitted, or payout override when amount is also sent.","type":"number","format":"float","example":25.5},"amount":{"description":"Percentage: submitted receipt/cost. Non-percentage: optional explicit line total.","type":"number","format":"float","example":120,"nullable":true},"quantity":{"description":"Miles, days, uses, sessions for template categories","type":"number","format":"float","example":50,"nullable":true},"reimbursableExpenseId":{"type":"integer","example":10,"nullable":true},"customName":{"type":"string","example":"Parking","nullable":true},"status":{"type":"string","enum":["pending","approved"],"example":"pending","nullable":true},"id":{"description":"Existing provider expense id when updating","type":"string","example":"123","nullable":true},"assignmentId":{"type":"string","example":"ASG-12345"},"serviceProviderId":{"type":"string","example":"USR-67890"},"uploadReceipt":{"description":"Receipt file (PDF, JPG, JPEG, max 2MB)","type":"string","format":"binary","nullable":true},"isDefault":{"type":"boolean","nullable":true},"billTo":{"description":"Who the expense is billed to; defaults to organization.","type":"string","enum":["organization","client"],"example":"organization","nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Expenses submitted for review.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expenses submitted for review."},"data":{"type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/finance/provider-expenses/bulk":{"post":{"tags":["Finances"],"summary":"Bulk store or update provider expenses","description":"**Required scope:** `finance:write`  \n**Roles:** admin, service-provider, scheduler\n\nBulk store or update provider expenses. Template percentage rows: amount or expense as receipt (required). Non-percentage: quantity and/or expense/amount as line total. maximumReimbursementCap: receipt cap for percentage (422); line-total cap for other bases. Receipt patch: omit document to keep file. Sync: submitted list is full desired set per group.","operationId":"ext_post_finance_provider_expenses_bulk","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"required":["providerExpenses"],"properties":{"affectFinancials":{"description":"Required when the change moves money on a work item whose linked finance document is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the change to those documents; false saves it and marks them out of sync.","type":"boolean","nullable":true},"providerExpenses":{"type":"array","items":{"description":"Expenses for one provider on a work item. Only providers currently assigned to the work item are processed.","required":["providerId"],"properties":{"entityId":{"description":"Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved.","type":"string","example":"ASG-SA2IVL","nullable":true},"providerId":{"type":"string","example":"SPR-H6OUI3"},"expenses":{"type":"array","items":{"required":["name"],"properties":{"id":{"description":"Existing expense id to update; omit to create.","type":"integer","example":42,"nullable":true},"name":{"type":"string","example":"Parking"},"amount":{"type":"number","minimum":0.01,"example":12.5,"nullable":true},"expense":{"description":"Unit amount, multiplied by quantity.","type":"number","minimum":0.01,"example":12.5,"nullable":true},"quantity":{"type":"number","minimum":0.01,"example":1,"nullable":true},"billTo":{"type":"string","enum":["organization","client"],"example":"organization","nullable":true},"document":{"description":"Receipt: pdf, jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isDefault":{"type":"boolean","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom expense.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"nullable":true},"rate":{"description":"Required when reimbursement_basic is percentage.","type":"number","minimum":0,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Expenses submitted for review.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expenses submitted for review."},"data":{"type":"array","items":{"properties":{"entityId":{"type":"string","example":"ASG-12345"},"providerId":{"type":"string","example":"USR-67890"},"expenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":123,"nullable":true},"name":{"type":"string","example":"Parking"},"amount":{"type":"number","format":"float","example":25.5},"isDefault":{"type":"boolean","example":true,"nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/finance/provider-expenses/calculate-preview":{"post":{"tags":["Finances"],"summary":"Preview calculated provider expense amount","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler\n\nRead-only. Computes the suggested expense amount from the work item's expense settings and optional quantity or submitted cost, using the same calculation as submit. Does not persist any record. serviceProviderId is optional for category-first preview; when quantity or provider cannot be resolved, returns partial metadata (rate, cap, basis) with calculatedAmount 0 and quantityReason indicating what is still needed. For per_day, quantity may be omitted and is derived as whole billable days from work-item scheduled hours (under 24h = 1 day; 24h+ = ceil(hours/24)); manual quantity must be a positive whole number. For per_unit with unit mile, quantity may be omitted when serviceProviderId is sent and is derived as round-trip mileage. For per_unit use/session, quantity is required for full calculation. For flat_amount, quantity defaults to 1 when omitted. For percentage, amount is required for full calculation; without amount returns partial preview with calculatedAmount 0.","operationId":"ext_post_finance_provider_expenses_calculate_preview","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workItemId":{"description":"Assignment (ASG-...) or shift id. Omit in add mode to resolve category from reimbursable_expenses catalog only.","type":"string","example":"ASG-12345","nullable":true},"reimbursableExpenseId":{"description":"Reimbursable expense category id from settings; required unless sourceReimbursableExpense is sent","type":"integer","example":10,"nullable":true},"sourceReimbursableExpense":{"description":"Custom-from-category path.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderId":{"description":"Service provider user id; optional for category-first partial preview, required for mileage auto-quantity","type":"string","example":"USR-67890","nullable":true},"quantity":{"description":"Miles, days, uses, etc. Optional when auto-derived or for partial preview","type":"number","format":"float","example":50,"nullable":true},"amount":{"description":"Submitted receipt/cost; required for full percentage calculation","type":"number","format":"float","example":120,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Calculation preview.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Calculation preview."},"data":{"properties":{"calculatedAmount":{"type":"number","format":"float","example":33.5},"suggestedExpense":{"description":"Same as calculatedAmount; suggested final amount if submit omits expense override","type":"number","format":"float","example":33.5},"reimbursementBasis":{"type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"per_unit"},"unit":{"description":"null for flat_amount and percentage; mile/day/use/session for other bases","type":"string","example":"mile","nullable":true},"unitRate":{"type":"number","format":"float","example":0.67},"quantity":{"description":"Defaults to 1 for per_unit/per_day when omitted and not auto-resolved; null for flat_amount and percentage","type":"number","format":"float","example":50,"nullable":true},"amount":{"description":"Percentage only: category rate (same as unitRate). Request amount is receipt/cost input.","type":"number","format":"float","example":10,"nullable":true},"quantityReason":{"description":"Set for percentage without receipt (not_applicable); null when quantity was resolved or defaulted","type":"string","example":"not_applicable","nullable":true},"servicePayBase":{"description":"For percentage basis: submitted receipt/cost used in formula (same column as persist service_pay_base_used)","type":"number","format":"float","example":120,"nullable":true},"capped":{"description":"True when maximum_reimbursement_cap clamped a calculated non-percentage line total; false for percentage (cap enforced on submit receipt only)","type":"boolean","example":false},"maximumCap":{"type":"number","format":"float","example":100,"nullable":true},"reimbursableExpenseId":{"description":"Category template id","type":"integer","example":10},"name":{"description":"Category name from snapshot or catalog","type":"string","example":"Mileage"},"expenseType":{"description":"Category expense type from snapshot or catalog","type":"string","example":"travel","nullable":true},"billTo":{"description":"Submit-style bill-to; from category snapshot","type":"string","enum":["organization","client"],"example":"organization","nullable":true},"isReceiptRequired":{"description":"Whether receipt is required for this category","type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error (request validation, category not found, category not attached to work item, invalid snapshot basis)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Expense category is not attached to this work item."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to calculate expense preview."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/finance/provider-expenses/upload-receipt":{"post":{"tags":["Finances"],"summary":"Upload or replace provider expense receipt","description":"**Required scope:** `finance:write`  \n**Roles:** admin, scheduler\n\nUploads or replaces a receipt for a provider expense. Allowed only for pending or changes_required expenses. Providers can upload for their own expenses; admin/scheduler/super-admin can upload for any provider.","operationId":"ext_post_finance_provider_expenses_upload_receipt","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"required":["receipt","expense_id","type"],"properties":{"receipt":{"description":"Receipt file (PDF, JPG, JPEG, max 2MB)","type":"string","format":"binary"},"expense_id":{"description":"Provider expense record id","type":"integer","example":123},"type":{"description":"Work item type for this expense","type":"string","enum":["assignment","shift"]}},"type":"object"}}}},"responses":{"200":{"description":"Receipt uploaded successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Receipt uploaded successfully."},"data":{"properties":{"expense_id":{"type":"integer","example":123},"type":{"type":"string","example":"assignment"},"uploadReceipt":{"type":"string","example":"https://s3.example.com/.../receipt.pdf"},"status":{"type":"string","example":"pending"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Expense not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"Invalid state or validation error","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/finance/provider-expenses/{id}":{"delete":{"tags":["Finances"],"summary":"Delete a provider expense","description":"**Required scope:** `finance:delete`  \n**Roles:** admin, scheduler\n\nDeletes a custom provider expense record when it is in pending or changes_required status. Providers can delete their own custom expenses; admin/scheduler/super-admin can delete any.","operationId":"ext_delete_finance_provider_expenses_By_id","parameters":[{"name":"id","in":"path","description":"Provider expense id","required":true,"schema":{"type":"integer","example":123}},{"name":"type","in":"query","description":"Work item type for this expense","required":true,"schema":{"type":"string","enum":["assignment","shift"],"example":"assignment"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Expense deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expense deleted successfully."},"data":{"type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Expense not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"Invalid type or status","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:delete","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/finance/provider-expenses/{id}/receipt":{"delete":{"tags":["Finances"],"summary":"Delete provider expense receipt","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nDeletes the receipt file for a provider expense. Allowed only for pending or changes_required expenses. Providers can delete for their own expenses; admin/scheduler/super-admin can delete for any.","operationId":"ext_delete_finance_provider_expenses_By_id_receipt","parameters":[{"name":"id","in":"path","description":"Provider expense id","required":true,"schema":{"type":"integer","example":123}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["work_item_id"],"properties":{"work_item_id":{"description":"Assignment (ASG-...) or shift (SFT-...) id for this expense","type":"string","example":"ASG-XXXXXX"}},"type":"object"}}}},"responses":{"200":{"description":"Receipt deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Receipt deleted successfully."},"data":{"type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Expense not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"Invalid work_item_id, no receipt to delete, or wrong status","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/finance/provider/service-revenue-chart":{"get":{"tags":["Finances"],"summary":"Get service revenue chart data for the authenticated provider","description":"**Required scope:** `finance:read`  \n**Roles:** admin, service-provider, scheduler\n\nRetrieves service revenue data grouped by service type (ASL, CART, etc.) over time for the authenticated provider. Only accessible by users with service-provider role. Returns data formatted for ApexCharts multi-series line chart display.","operationId":"ext_get_finance_provider_service_revenue_chart","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"period","in":"query","description":"Time period: all, today, this_week, this_month, daily, weekly, monthly. Default: monthly","required":false,"schema":{"type":"string","default":"monthly","enum":["all","today","this_week","this_month","daily","weekly","monthly"]}},{"name":"startDate","in":"query","description":"Start date for date range (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2026-01-01"}},{"name":"endDate","in":"query","description":"End date for date range (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2026-07-31"}}],"responses":{"200":{"description":"Service revenue chart data retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service revenue chart data retrieved successfully"},"data":{"properties":{"chart":{"properties":{"series":{"type":"array","items":{"properties":{"name":{"type":"string","example":"ASL"},"data":{"type":"array","items":{"type":"number"},"example":[100,150,200,290,250,240,300]}},"type":"object"}},"categories":{"type":"array","items":{"type":"string"},"example":["Jan 2026","Feb 2026","Mar 2026","Apr 2026","May 2026","Jun 2026","Jul 2026"]}},"type":"object"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid period parameter"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden - user is not a provider","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","service-provider","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/provider/{providerId}/assignments-shifts":{"get":{"tags":["Finances"],"summary":"Get assignments and shifts for a provider","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves published (non-deleted) assignments and shifts linked to a provider for manual payable creation. Soft eligibility hints (payable_eligible, provider_is_no_show) only mean this provider is not marked no-show — they ignore canceled pay, linked docs, and other gates. Charge engine / 422 validation remain authoritative.","operationId":"ext_get_finance_provider_By_providerId_assignments_shifts","parameters":[{"name":"providerId","in":"path","description":"Provider ID to get assignments and shifts for","required":true,"schema":{"type":"string","example":"SPR-XZQLQ1"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"document_id","in":"query","description":"Optional payable id (PAYB-…) already being edited/duplicated. Linked work items are returned even if soft-deleted or unpublished, with the same shape as create (including name). Must belong to this provider.","required":false,"schema":{"type":"string","example":"PAYB-ABC123"}}],"responses":{"200":{"description":"Assignments and shifts retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignments and shifts retrieved successfully"},"data":{"type":"array","items":{"properties":{"type":{"description":"Type of work","type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"description":"Unique identifier","type":"string","example":"ASG-12345"},"name":{"description":"Display name","type":"string","example":"Assignment Title"},"status":{"description":"Current status","type":"string","example":"Completed"},"status_slug":{"description":"Status slug","type":"string","example":"completed"},"finance_bucket":{"description":"Finance money bucket for document mixing rules","type":"string","enum":["standard","canceled","no-show"],"example":"standard"},"provider_is_no_show":{"description":"Provider picker: whether this provider is marked no-show or has a no-show reason recorded.","type":"boolean","example":false},"payable_eligible":{"description":"Soft hint only: false when this provider is marked no-show; does not consider canceled pay, linked docs, or expenses","type":"boolean","example":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Provider not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Provider not found"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/send-notification-attachment-options":{"get":{"tags":["Finances"],"summary":"Get send-notification PDF attachment options","description":"**Required scope:** `finance:read`\n\nReturns attachment presets and related finance documents for the Send Notification (send-message) flow. Requires query params type and document_id (same shape as finance download/send-email). Admin/scheduler: terminal primary documents (cancelled/void) return 422. Portal client/provider: eligible closed docs return 200 with none-only presets. Use before sending the message so the client can render the attachment picker.","operationId":"ext_get_finance_send_notification_attachment_options","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"type","in":"query","description":"Finance document type","required":true,"schema":{"type":"string","enum":["invoice","pro_forma","payable","payment_statement"],"example":"pro_forma"}},{"name":"document_id","in":"query","description":"Finance document ID for the given type","required":true,"schema":{"type":"string","example":"PF-001"}}],"responses":{"200":{"description":"Attachment options retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Attachment options retrieved successfully."},"data":{"properties":{"documentType":{"type":"string","enum":["invoice","pro_forma","payable","payment_statement"],"example":"pro_forma"},"documentId":{"type":"string","example":"PF-001"},"defaultSelection":{"description":"Invoice and payable default to primary_only; pro forma and payment statement default to none.","type":"string","enum":["none","primary_only","related_all","related_subset","both"],"example":"primary_only"},"supportsRelatedSubset":{"description":"True when rollup doc has related children and subset selection applies","type":"boolean","example":true},"presets":{"type":"array","items":{"properties":{"key":{"type":"string","enum":["none","primary_only","related_all","both"],"example":"both"},"label":{"type":"string","example":"Pro forma and all invoice PDFs"},"attachableDocuments":{"type":"array","items":{"properties":{"document_type":{"type":"string","example":"invoice"},"document_id":{"type":"string","example":"INV-001"}},"type":"object"}}},"type":"object"}},"relatedDocuments":{"type":"array","items":{"properties":{"document_id":{"type":"string","example":"INV-001"},"document_type":{"type":"string","example":"invoice"},"label":{"type":"string","example":"INV-001"},"total":{"type":"number","format":"float","example":1200,"nullable":true}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error, document not found, or terminal primary document (cancelled/void)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Cannot attach PDF — pro forma PF-001 is in a terminal status."},"errors":{"type":"string","example":"Failed to load attachment options"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":[],"x-fido-area":"Documents","x-fido-area-rank":6}},"/v1/finance/settings":{"get":{"tags":["Finances"],"summary":"Get finance settings by module","description":"**Required scope:** `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves billing settings for finance modules (invoice, payables, payments, proforma). When module is omitted, returns all modules. Optional client_id scopes invoice and proforma to effective client–organization payment term and automation flags.","operationId":"ext_get_finance_settings","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"module","in":"query","description":"Filter settings by module. Omit to return all modules.","required":false,"schema":{"type":"string","enum":["invoice","payables","payments","proforma"],"example":"invoice"}},{"name":"client_id","in":"query","description":"When set, invoice and proforma modules include effective payment_terms and effective flags. For module=invoice, also returns slim admin_fee org defaults (method/amount only).","required":false,"schema":{"type":"string","example":"CLT-XZQLQ1"}},{"name":"provider_id","in":"query","description":"When set with module=payables, returns slim provider admin_fee defaults (method/amount only).","required":false,"schema":{"type":"string","example":"USR-ABC123"}},{"name":"is_org_invoice","in":"query","description":"When true with module=invoice, returns org-billed admin_fee defaults without client_id.","required":false,"schema":{"type":"boolean","example":false}},{"name":"workitem_ids","in":"query","description":"Comma-separated assignment/shift IDs (ASG-..., SHF-...). With module=invoice and client_id, returns admin_fee with organization + per-provider rows (fee_source calculated).","required":false,"schema":{"type":"string","example":"ASG-ABC123,SHF-XYZ789"}}],"responses":{"200":{"description":"Finance settings retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Finance settings retrieved successfully."},"data":{"properties":{"payment_terms":{"description":"Default payment terms { id, label }","type":"object"},"notes":{"description":"Default notes","type":"string","example":"Added by the scheduler."},"summary":{"properties":{"tax_type":{"type":"object"},"tax_amount":{"type":"number","example":10},"discount_type":{"type":"object"},"discount_amount":{"type":"number","example":0}},"type":"object"},"effective":{"properties":{"auto_generate":{"type":"boolean","example":true},"auto_send":{"type":"boolean","example":true}},"type":"object","nullable":true}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid module parameter","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid module. Must be one of: invoice, payables, payments, proforma."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Client not found (when client_id is provided)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Client not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/work-item-expense-share":{"post":{"tags":["Finances"],"summary":"Approve/decline client expense share per expense line (admin/scheduler)","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nAdmin/scheduler can approve or decline a specific client's allocated share for one or more client-billable expense lines on an assignment or shift. Provide either reimbursable_expense_id (single) or reimbursable_expense_ids (bulk). decline_reason is required when action=decline. Decline is final per expense line.","operationId":"ext_post_finance_work_item_expense_share","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["work_item_type","work_item_id","client_id","action"],"properties":{"affectFinancials":{"description":"Required when the change moves money on a work item whose linked finance document is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the change to those documents; false saves it and marks them out of sync.","type":"boolean","nullable":true},"work_item_type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"work_item_id":{"type":"string","example":"ASG-ABC123"},"client_id":{"type":"string","example":"CLT-ABC123"},"action":{"type":"string","enum":["approve","decline","bill_to_organization","exclude"],"example":"approve"},"reimbursable_expense_id":{"description":"Single expense type id (required if reimbursable_expense_ids not provided)","type":"integer","example":12},"reimbursable_expense_ids":{"description":"Bulk expense type ids (required if reimbursable_expense_id not provided)","type":"array","items":{"type":"integer","example":12}},"service_provider_id":{"description":"Required when multiple providers are on the work item for template expense lines; auto-inferred when only one provider is assigned","type":"string","example":"USR-ABC123","nullable":true},"decline_reason":{"description":"Required when action=decline","type":"string","maxLength":2000,"example":"Not approved","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Expense share action completed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expense share action completed successfully."},"data":{"type":"object","oneOf":[{"description":"Single expense line response","properties":{"reimbursable_expense_id":{"type":"integer","example":12},"status":{"type":"string","enum":["pending","approved","declined"],"example":"approved"},"approved_at":{"type":"string","example":"2026-03-02T10:00:00+00:00","nullable":true},"approved_by":{"properties":{"id":{"type":"string","example":"USR-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"approved_share_total":{"type":"number","format":"float","example":10.5,"nullable":true},"declined_at":{"type":"string","example":null,"nullable":true},"declined_by":{"properties":{"id":{"type":"string","example":"USR-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"decline_reason":{"type":"string","example":null,"nullable":true}},"type":"object"},{"description":"Bulk response","properties":{"results":{"type":"array","items":{"properties":{"reimbursable_expense_id":{"type":"integer","example":12},"status":{"type":"string","enum":["pending","approved","declined"],"example":"approved"},"approved_at":{"type":"string","example":"2026-03-02T10:00:00+00:00","nullable":true},"approved_by":{"properties":{"id":{"type":"string","example":"USR-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"approved_share_total":{"type":"number","format":"float","example":10.5,"nullable":true},"declined_at":{"type":"string","example":null,"nullable":true},"declined_by":{"properties":{"id":{"type":"string","example":"USR-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"decline_reason":{"type":"string","example":null,"nullable":true}},"type":"object"}},"errors":{"type":"array","items":{"properties":{"reimbursable_expense_id":{"type":"integer","example":99},"message":{"type":"string","example":"Expense not in client's share."}},"type":"object"}}},"type":"object"}]}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/finance/work-items":{"get":{"tags":["Finances"],"summary":"Get detailed information for multiple assignments or shifts","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler\n\nRetrieves comprehensive details for multiple assignments or shifts including client, consumer, providers, expenses, and service rate breakdown. Supports two view types: AR (Accounts Receivable - client billing rates) and AP (Accounts Payable - provider compensation rates).","operationId":"ext_get_finance_work_items","parameters":[{"name":"ids","in":"query","description":"Comma-separated list of Assignment or Shift IDs to get details for","required":true,"schema":{"type":"string","example":"ASG-12345,SFT-67890"}},{"name":"type","in":"query","description":"View type: 'AR' for Accounts Receivable (client billing rates) or 'AP' for Accounts Payable (provider compensation rates). Defaults to 'AR'.","required":false,"schema":{"type":"string","enum":["AR","AP"],"example":"AR"}},{"name":"provider_id","in":"query","description":"Provider ID as string (optional). When type=AP, filters results and used to determine if each work item is already paid for this provider. If not provided and type=AP, tenant users receive data aggregated for all providers on the work item; portal service-provider users have this defaulted to their own ID when they are assigned to every requested work item (otherwise 403).","required":false,"schema":{"type":"string","example":"SPR-12345"}},{"name":"client_id","in":"query","description":"Client (billing) user ID as string (optional). For type=AR on client-billed work items, this must match the invoice billing client so the expenses object uses client expense share plus client-approved lines—the same behavior as tenant finance. When set, paid_label and paid_invoice_ids reflect this client. Tenant users may omit this for draft-style AR views. Portal client users: omitting client_id defaults to the authenticated client when they are linked to every requested work item; otherwise 403. Passing another client's ID returns 403.","required":false,"schema":{"type":"string","example":"USR-12345"}},{"name":"is_org_invoice","in":"query","description":"When type=AR and true, scopes linked_documents to active organization summary invoices (is_org_invoice=true, no client_id). Use for org-billed invoice picker context.","required":false,"schema":{"type":"boolean","example":true}},{"name":"invoice_id","in":"query","description":"When editing an invoice (type=AR): exclude this document from linked_documents. If the invoice is Canceled/Void, linked_documents is returned empty. Does not change is_included_in_billable_entity (still reflects any active link including this invoice).","required":false,"schema":{"type":"string","example":"INV-TOHWMO"}},{"name":"payable_id","in":"query","description":"When editing a payable (type=AP): exclude this document from linked_documents. If the payable is Canceled/Void, linked_documents is returned empty. Does not change is_included_in_billable_entity (still reflects any active link including this payable).","required":false,"schema":{"type":"string","example":"PAYB-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Work item details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Work item details retrieved successfully"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-12345"},"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"title":{"type":"string","example":"Assignment Title"},"total_estimated_cost":{"description":"Total estimated cost. For type=AR: sum of client billing rates (estimated_cost, using billable duration = max(actual, minimum billing duration)). For type=AP: sum of provider compensation rates (estimated_pay × billable duration = max(actual, minimum pay duration)).","type":"number","format":"float","example":500},"total_cost_with_expense":{"description":"total_estimated_cost + expenses.total (admin fees excluded), for both AR and AP.","type":"number","format":"float","example":575},"estimated_subtotal":{"description":"total_estimated_cost + expenses.total + organization_admin_fee + provider_admin_fee, for both AR and AP.","type":"number","format":"float","example":590},"organization_admin_fee":{"description":"Organization/scheduler admin fee for this work item. When client_id is provided and the work item is linked to an invoice, reflects the allocated invoice document org admin fee.","type":"number","format":"float","example":25},"provider_admin_fee":{"description":"Sum of provider admin fees for this work item. When client_id is provided and the work item is linked to an invoice, reflects the allocated invoice document provider admin fee.","type":"number","format":"float","example":15},"total_admin_fee":{"description":"organization_admin_fee + provider_admin_fee. When client_id is provided and the work item is linked to an invoice, these fields reflect allocated invoice document admin fees.","type":"number","format":"float","example":40},"location":{"description":"Location type label","type":"string","example":"Onsite"},"timezone":{"type":"string","example":"America/New_York"},"start_date":{"type":"string","example":"2025-04-21"},"end_date":{"type":"string","example":"2025-04-21"},"start_time":{"type":"string","example":"09:00 AM"},"end_time":{"type":"string","example":"05:00 PM"},"client":{"properties":{"id":{"type":"string","example":"CLT-12345"},"name":{"type":"string","example":"John Doe"},"email":{"type":"string","example":"user@example.com"},"phone":{"type":"string","example":"+1234567890"},"logo":{"type":"string","example":null,"nullable":true}},"type":"object"},"consumer":{"properties":{"id":{"type":"string","example":"CON-67890"},"name":{"type":"string","example":"Jane Smith"},"email":{"type":"string","example":"user@example.com"},"phone":{"type":"string","example":"+1234567891"},"logo":{"type":"string","example":null,"nullable":true}},"type":"object","nullable":true},"assignedProviders":{"type":"array","items":{"properties":{"locationType":{"type":"string","example":"onsite"},"assignServiceTypeInfo":{"type":"array","items":{"properties":{"serviceType":{"type":"string","example":"Personal Care"},"assigned":{"type":"integer","example":2},"total":{"type":"integer","example":3},"providers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-11111"},"logo":{"type":"string","nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"}},"paid_label":{"description":"When client_id (AR) or provider_id (AP) is provided: 'Paid in invoice' or 'Paid in payable' if this work item is already on a paid document for that client/provider; null otherwise.","type":"string","example":"Paid in invoice","nullable":true},"paid_invoice_ids":{"description":"When type=AR and client_id provided: ids of all paid invoices this work item is on; empty array otherwise.","type":"array","items":{"type":"string"},"example":["INV-12345"]},"paid_payable_ids":{"description":"When type=AP and provider_id provided: ids of all paid payables this work item is on; empty array otherwise.","type":"array","items":{"type":"string"},"example":["PAY-67890"]},"is_included_in_billable_entity":{"description":"True when the work item has any active (non-terminal) invoice/payable link for the scoped client/provider, including the document identified by invoice_id/payable_id when editing.","type":"boolean","example":true},"linked_documents":{"description":"Active non-terminal finance documents that currently bill this work item for the scoped party. When invoice_id/payable_id is set for edit, that document is omitted; when that context document is Canceled/Void, this array is empty.","type":"array","items":{"properties":{"id":{"type":"string","example":"INV-TOHWMO"},"type":{"type":"string","enum":["invoice","payable"],"example":"invoice"},"status":{"type":"string","example":"Paid"},"status_code":{"type":"string","example":"INVOICE_PAID"}},"type":"object"}},"cancel_breakdown":{"description":"Present only for canceled work items. Mirrors the `cancellation` section from `/{module}/{id}/cancellation-setup` (clients + providerPolicy + providers). Returns null for non-canceled items, canceled items with no estimated rows, or per-item breakdown computation failures.","type":"object","nullable":true},"no_show_breakdown":{"description":"Present only for no-show work items that are not canceled. Mirrors the `noShow` section from `/{module}/{id}/cancellation-setup` (clients + providers + totals + no-show flags). Returns null for canceled, non-no-show, missing-row, or per-item breakdown computation failure cases.","type":"object","nullable":true},"expenses":{"properties":{"items":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Mileage"},"rate":{"type":"number","format":"float","example":50},"unit":{"type":"string","example":"mile"},"reimbursementBasis":{"type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"per_unit","nullable":true},"quantity":{"description":"Expense quantity; null for flat_amount and percentage bases","type":"number","format":"float","example":24.5,"nullable":true},"quantityReason":{"description":"How quantity was resolved: db, preview, catalog_preview, fallback_one, not_applicable, unknown_basis","type":"string","example":"preview","nullable":true}},"type":"object"}},"total":{"type":"number","format":"float","example":50}},"type":"object"},"serviceRateBreakdown":{"description":"Service rate breakdown. For type=AR: shows client billing rates from AssignmentEstimatedCost/ShiftEstimatedCost tables. For type=AP: shows provider compensation rates from AssignmentProviderEstimatedPayRate/ShiftProviderEstimatedPayRate tables. If provider_id is provided with type=AP, only shows rates for that provider.","type":"array","items":{"properties":{"label":{"description":"Rate type or service type label. For type=AR: from rate_type. For type=AP: from rateType name or serviceType name.","type":"string","example":"Standard Rate"},"rate":{"description":"Rate per hour. For type=AR: client billing rate. For type=AP: provider compensation rate (estimated_pay).","type":"number","format":"float","example":25},"hours":{"description":"Hours worked. For type=AR: from hours field. For type=AP: from duration field.","type":"number","format":"float","example":8},"cost":{"description":"Total cost (rate × billable hours, where billable = max(actual, minimum duration)). For type=AR: from estimated_cost. For type=AP: estimated_pay × billable duration. Rows also expose actual_hours/billable_hours/minimum_hours/minimum_applied. Describes the service as scheduled and is NOT replaced when the work item is canceled.","type":"number","format":"float","example":200},"billable_amount":{"description":"What this row actually bills/pays. Equals `cost` normally; on a canceled AR row it is that row's share of the client cancellation fee (0 when the client is not billed for cancellation), since a flat/prorated fee does not derive from rate × duration. Use this — not `cost` — to total a canceled item.","type":"number","format":"float","example":25},"time_slot":{"description":"Time slot (for AR type only, empty string for AP type)","type":"string","example":"09:00 AM - 05:00 PM"},"unit":{"description":"Billing unit: 'hour' or 'minute'","type":"string","example":"hour"}},"type":"object"}}},"type":"object"}}},"type":"object"}}}},"400":{"description":"Missing required parameter","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Missing required parameter: ids"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Portal client or service-provider cannot access these work items or attempted to use another party's ID","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/work-items/{id}/child-finance-overview":{"get":{"tags":["Finances"],"summary":"Finance overview across a recurring work item's occurrences","description":"**Required scope:** `finance:read`  \n**Roles:** admin, client, scheduler\n\nTotals and the active invoices and payables linked to each child occurrence of a parent assignment or shift. A client caller does not see totalProviderPayouts, the payables list or payableNotExist.","operationId":"ext_get_finance_work_items_By_id_child_finance_overview","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"Parent assignment (ASG-) or shift (SFT-) id.","required":true,"schema":{"type":"string","example":"ASG-YZXCIT"}}],"responses":{"200":{"description":"Overview retrieved","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Child finance overview retrieved successfully"},"data":{"properties":{"childOverallData":{"properties":{"totalBilledToClients":{"type":"number","example":1250},"totalProviderPayouts":{"type":"number","example":900},"netProfitLoss":{"type":"number","example":350}},"type":"object"},"childInvoiceAndPayables":{"properties":{"invoices":{"type":"array","items":{"properties":{"id":{"description":"Child occurrence id.","type":"string","example":"ASG-YZXCIT-C2"},"type":{"type":"string","enum":["assignment","shift"]},"title":{"type":"string","nullable":true},"status":{"properties":{"id":{"type":"integer"},"label":{"type":"string"},"slug":{"type":"string"}},"type":"object","nullable":true},"invoices":{"type":"array","items":{"properties":{"id":{"type":"string","example":"INV-EWDM3W"},"status":{"type":"string","example":"Sent","nullable":true},"statusCode":{"type":"string","nullable":true},"issueDate":{"description":"In the organization's date format.","type":"string","nullable":true}},"type":"object"}}},"type":"object"}},"payables":{"description":"Same shape as invoices, with a payables list in place of invoices.","type":"array","items":{"type":"object"}}},"type":"object"},"invoiceNotExist":{"type":"boolean","example":false},"payableNotExist":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:read","x-fido-module":"finance","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Overview, clients and work items","x-fido-area-rank":3}},"/v1/finance/{module}/document/files":{"delete":{"tags":["Finances"],"summary":"Delete files attached to finance documents","description":"**Required scope:** `finance:edit`  \n**Roles:** admin, scheduler\n\nRemoves uploaded files from invoices, pro formas, payables or payment statements by file id.","operationId":"ext_delete_finance_By_module_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"module","in":"path","required":true,"schema":{"type":"string","enum":["invoices","pro-formas","payables","payment-statements"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["fileIds"],"properties":{"fileIds":{"type":"array","items":{"type":"integer","example":12},"minItems":1}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Pro formas or payment statements are disabled for this organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"fileIds missing or not integers.","content":{"application/json":{"schema":{"description":"Validation failures use their own envelope — status rather than success, and no code.","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages. Nested keys are collapsed onto the field the form renders.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:edit","x-fido-module":"finance","x-fido-roles":["admin","scheduler"],"x-fido-area":"Documents","x-fido-area-rank":6}},"/v1/forms":{"get":{"tags":["Forms"],"summary":"List all forms","description":"**Required scope:** `forms:read`  \n**Roles:** admin, scheduler\n\nRetrieve a paginated list of forms with filtering and search capabilities.","operationId":"ext_get_forms","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","description":"Search by name, description, or form code","required":false,"schema":{"type":"string"}},{"name":"scope","in":"query","description":"Filter by scope (internal, external)","required":false,"schema":{"type":"string","enum":["internal","external"]}},{"name":"localSearch","in":"query","description":"Search within the current results.","required":false,"schema":{"type":"string"}},{"name":"formType","in":"query","description":"Filter by form type.","required":false,"schema":{"type":"string","enum":["default","custom"]}},{"name":"moduleType","in":"query","description":"Filter by module (assignment, shift, client, consumer, …). Send all to ignore the filter.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by status id.","required":false,"schema":{"type":"string"}},{"name":"isPublished","in":"query","description":"Filter published (true) or draft (false) forms.","required":false,"schema":{"type":"boolean"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Rows per page (default 10).","required":false,"schema":{"type":"integer","example":10}},{"name":"columns","in":"query","description":"Comma-separated columns to search in.","required":false,"schema":{"type":"string"}},{"name":"assignedTo","in":"query","description":"Filter by the Assign To column: forms bound to this client, consumer or provider ID. Blank means no filter.","required":false,"schema":{"type":"string","example":"CSM-12FGT4"}},{"name":"assignTo","in":"query","description":"Older name for assignedTo, read only when assignedTo is blank.","required":false,"deprecated":true,"schema":{"type":"string","example":"CSM-12FGT4"}},{"name":"externalVisibility","in":"query","description":"Filter by the External Visibility column. Returns external forms only.","required":false,"schema":{"type":"string","enum":["public","private"],"example":"private"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"string"},"name":{"type":"string","example":"Example name"},"description":{"type":"string","example":"Short human-readable description."},"isPublished":{"type":"boolean","example":true},"formType":{"type":"string","example":"string"},"moduleType":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"version":{"type":"integer","example":1},"scope":{"type":"string","example":"string"},"assignedTo":{"type":"string","example":"string"},"usage":{"type":"integer","example":1},"lastUsedDate":{"type":"string","format":"date","example":"2026-01-15"},"customFields":{"type":"integer","example":1},"lastUpdated":{"type":"string","example":"string"},"externalVisibility":{"properties":{"id":{"type":"string","example":"private"},"label":{"type":"string","example":"Private"}},"type":"object"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":"string","name":"Example name","description":"Short human-readable description.","isPublished":true,"formType":"string","moduleType":{"id":"string","label":"Example label"},"status":{"id":1,"label":"Example label"},"version":1,"scope":"string","assignedTo":"string","usage":1,"lastUsedDate":"2026-01-15","customFields":1,"lastUpdated":"string","externalVisibility":{"id":"private","label":"Private"}}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":2}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:read","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0},"post":{"tags":["Forms"],"summary":"Create a new form","description":"**Required scope:** `forms:write`  \n**Roles:** admin, scheduler\n\nCreate a new internal or external form with groups and fields. A Contact form (form.moduleType.id contact) must be external, cannot hold file fields, and may carry form.notifyTo, form.notifyCc and form.notifyBcc (lists of ASCII email addresses; at most 50 in all; Bcc is set by the admin role only). Empty To means the org's admins and schedulers.","operationId":"ext_post_forms","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"A custom form: its settings under `form`, and its field groups under `groups`. The groups sent replace the stored ones.","required":["form","groups"],"properties":{"scope":{"description":"external requires form.submissionStatus and form.externalVisibility.","type":"string","enum":["internal","external"],"nullable":true},"form":{"required":["name","status","moduleType"],"properties":{"id":{"description":"Form code of an existing form.","type":"string","nullable":true},"name":{"type":"string","maxLength":255,"example":"Intake form"},"description":{"type":"string","nullable":true},"isPublished":{"description":"Publishing turns on the stricter field rules.","type":"boolean","example":false,"nullable":true},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"moduleType":{"description":"The module the form collects, such as assignment, shift, client or consumer.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"submissionStatus":{"description":"Status a submission lands in. Required when scope is external.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"externalVisibility":{"description":"Required for an external form.","properties":{"id":{"type":"string","enum":["public","private"]},"label":{"type":"string"}},"type":"object","nullable":true},"assignTo":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"isCustom":{"type":"boolean","nullable":true}},"type":"object","nullable":true},"clientId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"applicableLocationId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"financeReferenceId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"multiStep":{"description":"Show groups that start a step as separate pages.","type":"boolean","nullable":true},"reviewStep":{"description":"Add a review page before submit.","type":"boolean","nullable":true},"settings":{"properties":{"thankYouMessage":{"type":"string","maxLength":500,"nullable":true}},"type":"object","nullable":true},"notifyTo":{"description":"Submission notice recipients: email addresses.","type":"array","items":{"type":"string"},"nullable":true},"notifyCc":{"type":"array","items":{"type":"string"},"nullable":true},"notifyBcc":{"type":"array","items":{"type":"string"},"nullable":true}},"type":"object"},"groups":{"type":"array","items":{"required":["name","order","fields"],"properties":{"id":{"description":"Existing group to keep.","type":"integer","nullable":true},"name":{"type":"string","example":"Contact details"},"order":{"type":"integer","example":1},"startsStep":{"type":"boolean","nullable":true},"stepTitle":{"type":"string","maxLength":255,"nullable":true},"fields":{"type":"array","items":{"properties":{"id":{"description":"Existing field to keep.","type":"integer","nullable":true},"label":{"type":"string","example":"Preferred contact time"},"type":{"type":"string","enum":["text","textarea","number","email","phone","date","time","select","checkbox","toggle","file","radio","group"]},"isRequired":{"type":"boolean","nullable":true},"isVisible":{"type":"boolean","nullable":true},"isArchived":{"type":"boolean","nullable":true},"order":{"type":"integer","example":1},"settings":{"description":"Per-type settings: ui (placeholder, style), validation, options [{label, value}], default, selectType / checkboxType / fileType (single or multiple), maxFileSize, toggleOnLabel / toggleOffLabel, and subFields for a group field.","type":"object","nullable":true}},"type":"object"},"minItems":1}},"type":"object"}}},"type":"object"}}}},"responses":{"201":{"description":"Form created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"New Form"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":1,"name":"New Form"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:write","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/fields":{"get":{"tags":["Forms"],"summary":"List selectable form fields","description":"**Required scope:** `forms:read`  \n**Roles:** admin, scheduler\n\nRetrieve default (module-specific) or custom (org-wide reusable) field definitions for the form builder's field picker. For options=custom, each item is annotated with usage stats (active/historical forms, submission count) so the caller can build its own delete or archive confirmation.","operationId":"ext_get_forms_fields","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"options","in":"query","description":"Which set of fields to return.","required":true,"schema":{"type":"string","enum":["default","custom"]}},{"name":"module","in":"query","description":"Module key, required when options=default.","required":false,"schema":{"type":"string","enum":["assignment","shift","client","consumer","service_provider","client_location","client_request","consumer_request","request","contact"]}},{"name":"type","in":"query","description":"When module=request, disambiguates to client_request or consumer_request.","required":false,"schema":{"type":"string","enum":["client","consumer"]}},{"name":"assignTo","in":"query","description":"For assignment/shift default fields: 'client' or 'organization'.","required":false,"schema":{"type":"string","enum":["client","organization"]}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"fieldId":{"type":"integer","example":1},"fieldKey":{"type":"string","example":"string"},"label":{"type":"string","example":"string"},"type":{"type":"string","example":"string"},"module":{"type":"string","example":"string"},"isDefault":{"type":"boolean","example":true},"isRequired":{"type":"boolean","example":true},"isVisible":{"type":"boolean","example":true},"isArchived":{"type":"boolean","example":true},"order":{"type":"integer","example":1},"settings":{"type":"array","items":{"type":"object"}},"isAlreadyUsed":{"type":"boolean","example":true},"activeFormsCount":{"type":"string","example":"string"},"historicalFormsCount":{"type":"string","example":"string"},"submissionsCount":{"type":"string","example":"string"},"canPermanentlyDelete":{"type":"boolean","example":true},"canArchive":{"type":"boolean","example":true},"activeForms":{"type":"array","items":{"type":"object"}},"historicalForms":{"type":"array","items":{"type":"object"}}},"type":"object"}}},"type":"object"},"example":{"success":true,"data":[{"id":1,"fieldId":1,"fieldKey":"string","label":"string","type":"string","module":"string","isDefault":true,"isRequired":true,"isVisible":true,"isArchived":true,"order":1,"settings":[],"isAlreadyUsed":true,"activeFormsCount":"string","historicalFormsCount":"string","submissionsCount":"string","canPermanentlyDelete":true,"canArchive":true,"activeForms":[],"historicalForms":[]}]}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:read","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/fields/{fieldId}":{"delete":{"tags":["Forms"],"summary":"Permanently delete a master custom field","description":"**Required scope:** `forms:edit`  \n**Roles:** admin, scheduler\n\nHard-deletes a master field when it is not placed on any active form and carries no historical submission data. Otherwise blocked with a 422 explaining why (still in active use, or has historical data) so the caller can archive the field instead.","operationId":"ext_delete_forms_fields_By_fieldId","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"fieldId","in":"path","description":"Master field id (form_fields.id)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Field deleted","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Custom field deleted."}},"type":"object"},"example":{"success":true,"message":"Custom field deleted."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The specified field does not exist.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"Deletion blocked — field is in active use or has historical data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:edit","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/fields/{fieldId}/{action}":{"post":{"tags":["Forms"],"summary":"Archive or unarchive a master custom field","description":"**Required scope:** `forms:edit`  \n**Roles:** admin, scheduler\n\nSets the master field's archived status per the action path segment: 'archive' hides it from the field picker/new placements, 'unarchive' restores it.","operationId":"ext_post_forms_fields_By_fieldId_By_action","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"fieldId","in":"path","description":"Master field id (form_fields.id)","required":true,"schema":{"type":"integer"}},{"name":"action","in":"path","description":"Whether to archive or unarchive the field","required":true,"schema":{"type":"string","enum":["archive","unarchive"]}}],"responses":{"200":{"description":"Archive status updated","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Custom field archived."},"data":{"properties":{"fieldId":{"type":"integer","example":1},"fieldKey":{"type":"string","example":"full_name"},"isArchived":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Custom field archived.","data":{"fieldId":1,"fieldKey":"full_name","isArchived":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The specified field does not exist.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:edit","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/module-fields/{module}":{"get":{"tags":["Forms"],"summary":"Fetch custom-fields schema for a module (add-mode)","description":"**Required scope:** `forms:read`  \n**Roles:** admin, scheduler\n\nReturns an array of customFields response shapes (form + groups + fields with default values) — one entry per active internal form matching the given scope, merged with the module's generic form. Used when rendering the add screen for a module that does not yet have a record.","operationId":"ext_get_forms_module_fields_By_module","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"module","in":"path","description":"Module key (client, consumer, assignment, shift, service-provider, client-location)","required":true,"schema":{"type":"string","enum":["client","consumer","assignment","shift","service-provider","client-location"]}},{"name":"assignTo","in":"query","description":"Form scope for assignment/shift: 'organization' (generic) or 'client' (client-specific, with clientId).","required":false,"schema":{"type":"string","enum":["organization","client"]}},{"name":"clientId","in":"query","description":"Client id (CLT-…) to fetch the client-specific form for assignment/shift/client-location.","required":false,"schema":{"type":"string","example":"CLT-8LE81N"}},{"name":"locationId","in":"query","description":"Client location id (CLTLOC-…) to fetch the location-specific form (client-location).","required":false,"schema":{"type":"string","example":"CLTLOC-423LS"}}],"responses":{"200":{"description":"Form fields retrieved, or null when no active form applies.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Form fields retrieved!"},"data":{"description":"One entry per active form in scope, each in the same shape the form-details endpoint returns, with each field's empty value filled in, archived placements dropped and a usage count attached. Sent as null — not an empty array — when no active form applies.","type":"array","items":{"properties":{"form":{"properties":{"id":{"description":"The form code.","type":"string","example":"FRM-7KQ2PA"},"name":{"type":"string","example":"Intake"},"description":{"type":"string","nullable":true},"isPublished":{"type":"boolean","example":true},"formType":{"type":"string","example":"internal","nullable":true},"moduleType":{"properties":{"id":{"type":"string","example":"client"},"label":{"type":"string","example":"Client"}},"type":"object","nullable":true},"status":{"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Active"}},"type":"object","nullable":true},"assignTo":{"properties":{"id":{"type":"string","example":"organization"},"label":{"type":"string","example":"Organization"},"isCustom":{"type":"boolean","example":false}},"type":"object","nullable":true},"version":{"type":"integer","example":2,"nullable":true},"multiStep":{"type":"boolean","example":false},"reviewStep":{"description":"Only meaningful while multiStep is true.","type":"boolean","example":false},"externalVisibility":{"properties":{"id":{"type":"string","enum":["public","private"],"example":"private"},"label":{"type":"string","example":"Private"}},"type":"object","nullable":true},"lastUsedDate":{"type":"string","example":"01/15/2025","nullable":true},"settings":{"type":"object","nullable":true}},"type":"object"},"startsStep":{"type":"integer","example":1,"nullable":true},"groups":{"description":"Field groups in render order; a single-step form has one.","type":"array","items":{"properties":{"label":{"type":"string","example":"Contact","nullable":true},"isRequired":{"type":"boolean","example":false},"isArchived":{"type":"boolean","example":false},"fields":{"type":"array","items":{"properties":{"fieldKey":{"type":"string","example":"preferred_name"},"label":{"type":"string","example":"Preferred name"},"type":{"type":"string","example":"text"},"isDefault":{"type":"boolean","example":false},"isRequired":{"type":"boolean","example":true},"isArchived":{"type":"boolean","example":false},"value":{"description":"The field's type-correct empty value in add mode: false, null, [] or the empty string.","nullable":true},"usageCount":{"description":"Active forms this field appears on.","type":"integer","example":3,"nullable":true},"settings":{"type":"object","nullable":true},"ui":{"properties":{"placeholder":{"type":"string","nullable":true},"style":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"cssClass":{"type":"string","nullable":true},"checkboxType":{"type":"string","nullable":true}},"type":"object","nullable":true},"validation":{"properties":{"required":{"type":"boolean","example":true}},"type":"object","nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"},"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Unsupported module","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:read","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/{formCode}/assigned-users/{assignedUserId}/{option}":{"delete":{"tags":["Forms"],"summary":"Remove a user/location/finance record from a form's Assign To list","description":"**Required scope:** `forms:edit`  \n**Roles:** admin, scheduler\n\n'removeOnly' soft-deletes the assignment row only — previously submitted data stays intact on the subject's record as historical data. 'permanentlyRemove' (alias 'removeAndDelete', the value the admin screen sends) additionally purges that subject's stored data for this form and hard-deletes the assignment row.","operationId":"ext_delete_forms_By_formCode_assigned_users_By_assignedUserId_By_option","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"formCode","in":"path","description":"Form code (FRM-…)","required":true,"schema":{"type":"string","example":"FRM-XYZ123"}},{"name":"assignedUserId","in":"path","description":"form_assigned_users.id","required":true,"schema":{"type":"integer"}},{"name":"option","in":"path","description":"removeOnly unassigns the user; permanentlyRemove also deletes their historical submissions. removeAndDelete is accepted as an alias of permanentlyRemove.","required":true,"schema":{"type":"string","enum":["removeOnly","permanentlyRemove","removeAndDelete"]}},{"name":"reason","in":"query","description":"Optional note, max 500 characters, recorded in the audit entry when submissions are deleted. May also be sent in the body.","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"Assignment removed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"User removed from form assignment."}},"type":"object"},"example":{"success":true,"message":"User removed from form assignment."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The specified assignment does not exist on this form.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"option is not removeOnly, permanentlyRemove or removeAndDelete.","content":{"application/json":{"schema":{"description":"Validation failures use their own envelope — status rather than success, and no code.","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages. Nested keys are collapsed onto the field the form renders.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:edit","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/{formCode}/group-fields/{groupFieldId}":{"delete":{"tags":["Forms"],"summary":"Remove a field placement from a form","description":"**Required scope:** `forms:edit`  \n**Roles:** admin, scheduler\n\nRemoves one field placement (form_group_fields row) from this form's groups. Does not affect the underlying master field or its placements on other forms.","operationId":"ext_delete_forms_By_formCode_group_fields_By_groupFieldId","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"formCode","in":"path","description":"Form code (FRM-…)","required":true,"schema":{"type":"string","example":"FRM-XYZ123"}},{"name":"groupFieldId","in":"path","description":"Field placement id (form_group_fields.id)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Field removed from form","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Field removed from form."}},"type":"object"},"example":{"success":true,"message":"Field removed from form."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The specified field does not exist on this form.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:edit","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/{formCode}/group-fields/{groupFieldId}/{action}":{"post":{"tags":["Forms"],"summary":"Archive or unarchive a field placement on a form","description":"**Required scope:** `forms:edit`  \n**Roles:** admin, scheduler\n\nSets a field placement's archived status on this specific form only (the master field and its placements on other forms are unaffected), per the action path segment: 'archive' or 'unarchive'.","operationId":"ext_post_forms_By_formCode_group_fields_By_groupFieldId_By_action","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"formCode","in":"path","description":"Form code (FRM-…)","required":true,"schema":{"type":"string","example":"FRM-XYZ123"}},{"name":"groupFieldId","in":"path","description":"Field placement id (form_group_fields.id)","required":true,"schema":{"type":"integer"}},{"name":"action","in":"path","description":"Whether to archive or unarchive the placement","required":true,"schema":{"type":"string","enum":["archive","unarchive"]}}],"responses":{"200":{"description":"Archive status updated","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Field archived on this form."},"data":{"properties":{"id":{"type":"integer","example":5},"isArchived":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Field archived on this form.","data":{"id":5,"isArchived":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The specified field does not exist on this form.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:edit","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/forms/{form}":{"delete":{"tags":["Forms"],"summary":"Delete a form","description":"**Required scope:** `forms:delete`  \n**Roles:** admin, scheduler\n\nSoft delete a form.","operationId":"ext_delete_forms_By_form","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"form","in":"path","description":"Form ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Form deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Form deleted successfully"}},"type":"object"},"example":{"success":true,"message":"Form deleted successfully"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:delete","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0},"get":{"tags":["Forms"],"summary":"Get form details","description":"**Required scope:** `forms:read`  \n**Roles:** admin, scheduler\n\nRetrieve details of a specific form including groups, fields, and locations. For a Contact form (moduleType contact) `data.form` also carries notifyTo and notifyCc (string lists), notifyBcc (admin role only; the key is absent for anyone else), notifyGroupEligibleCount, emailNoticesAvailable and hasSubmissions. These keys are never returned by the public GET /embed/{formid}.","operationId":"ext_get_forms_By_form","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"form","in":"path","description":"Form ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"form":{"properties":{"id":{"type":"string","example":"FRM-E-SPR-AB12CD"},"name":{"type":"string","example":"Form Name"},"version":{"type":"integer","example":3},"multiStep":{"type":"boolean","example":true},"reviewStep":{"type":"boolean","example":false}},"type":"object"},"groups":{"type":"array","items":{"properties":{"id":{"type":"integer","example":12},"name":{"type":"string","example":"About you"},"order":{"type":"integer","example":1},"startsStep":{"type":"boolean","example":true},"stepTitle":{"type":"string","example":"About you"},"fields":{"type":"array","items":{"type":"object"}}},"type":"object"}},"scope":{"type":"string","example":"string"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"form":{"id":"FRM-E-SPR-AB12CD","name":"Form Name","version":3,"multiStep":true,"reviewStep":false},"groups":[{"id":12,"name":"About you","order":1,"startsStep":true,"stepTitle":"About you","fields":[]}],"scope":"string"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Form not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:read","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0},"put":{"tags":["Forms"],"summary":"Update a form","description":"**Required scope:** `forms:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing form. Groups and Fields are fully replaced. On a Contact form a recipient list (form.notifyTo, notifyCc, notifyBcc) that is not sent is left as stored, and one sent empty is cleared; the module type cannot change once the form has submissions.","operationId":"ext_put_forms_By_form","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"form","in":"path","description":"Form ID","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"A custom form: its settings under `form`, and its field groups under `groups`. The groups sent replace the stored ones.","required":["form","groups"],"properties":{"scope":{"description":"external requires form.submissionStatus and form.externalVisibility.","type":"string","enum":["internal","external"],"nullable":true},"form":{"required":["name","status","moduleType"],"properties":{"id":{"description":"Form code of an existing form.","type":"string","nullable":true},"name":{"type":"string","maxLength":255,"example":"Intake form"},"description":{"type":"string","nullable":true},"isPublished":{"description":"Publishing turns on the stricter field rules.","type":"boolean","example":false,"nullable":true},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"moduleType":{"description":"The module the form collects, such as assignment, shift, client or consumer.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"submissionStatus":{"description":"Status a submission lands in. Required when scope is external.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"externalVisibility":{"description":"Required for an external form.","properties":{"id":{"type":"string","enum":["public","private"]},"label":{"type":"string"}},"type":"object","nullable":true},"assignTo":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"isCustom":{"type":"boolean","nullable":true}},"type":"object","nullable":true},"clientId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"applicableLocationId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"financeReferenceId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"multiStep":{"description":"Show groups that start a step as separate pages.","type":"boolean","nullable":true},"reviewStep":{"description":"Add a review page before submit.","type":"boolean","nullable":true},"settings":{"properties":{"thankYouMessage":{"type":"string","maxLength":500,"nullable":true}},"type":"object","nullable":true},"notifyTo":{"description":"Submission notice recipients: email addresses.","type":"array","items":{"type":"string"},"nullable":true},"notifyCc":{"type":"array","items":{"type":"string"},"nullable":true},"notifyBcc":{"type":"array","items":{"type":"string"},"nullable":true}},"type":"object"},"groups":{"type":"array","items":{"required":["name","order","fields"],"properties":{"id":{"description":"Existing group to keep.","type":"integer","nullable":true},"name":{"type":"string","example":"Contact details"},"order":{"type":"integer","example":1},"startsStep":{"type":"boolean","nullable":true},"stepTitle":{"type":"string","maxLength":255,"nullable":true},"fields":{"type":"array","items":{"properties":{"id":{"description":"Existing field to keep.","type":"integer","nullable":true},"label":{"type":"string","example":"Preferred contact time"},"type":{"type":"string","enum":["text","textarea","number","email","phone","date","time","select","checkbox","toggle","file","radio","group"]},"isRequired":{"type":"boolean","nullable":true},"isVisible":{"type":"boolean","nullable":true},"isArchived":{"type":"boolean","nullable":true},"order":{"type":"integer","example":1},"settings":{"description":"Per-type settings: ui (placeholder, style), validation, options [{label, value}], default, selectType / checkboxType / fileType (single or multiple), maxFileSize, toggleOnLabel / toggleOffLabel, and subFields for a group field.","type":"object","nullable":true}},"type":"object"},"minItems":1}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Form updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"integer","example":1},"version":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":1,"version":2}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:edit","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0},"patch":{"tags":["Forms"],"summary":"Update a form","description":"**Required scope:** `forms:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing form. Groups and Fields are fully replaced. On a Contact form a recipient list (form.notifyTo, notifyCc, notifyBcc) that is not sent is left as stored, and one sent empty is cleared; the module type cannot change once the form has submissions.","operationId":"ext_patch_forms_By_form","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"form","in":"path","description":"Form ID","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"A custom form: its settings under `form`, and its field groups under `groups`. The groups sent replace the stored ones.","required":["form","groups"],"properties":{"scope":{"description":"external requires form.submissionStatus and form.externalVisibility.","type":"string","enum":["internal","external"],"nullable":true},"form":{"required":["name","status","moduleType"],"properties":{"id":{"description":"Form code of an existing form.","type":"string","nullable":true},"name":{"type":"string","maxLength":255,"example":"Intake form"},"description":{"type":"string","nullable":true},"isPublished":{"description":"Publishing turns on the stricter field rules.","type":"boolean","example":false,"nullable":true},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"moduleType":{"description":"The module the form collects, such as assignment, shift, client or consumer.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"submissionStatus":{"description":"Status a submission lands in. Required when scope is external.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"externalVisibility":{"description":"Required for an external form.","properties":{"id":{"type":"string","enum":["public","private"]},"label":{"type":"string"}},"type":"object","nullable":true},"assignTo":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"isCustom":{"type":"boolean","nullable":true}},"type":"object","nullable":true},"clientId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"applicableLocationId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"financeReferenceId":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"multiStep":{"description":"Show groups that start a step as separate pages.","type":"boolean","nullable":true},"reviewStep":{"description":"Add a review page before submit.","type":"boolean","nullable":true},"settings":{"properties":{"thankYouMessage":{"type":"string","maxLength":500,"nullable":true}},"type":"object","nullable":true},"notifyTo":{"description":"Submission notice recipients: email addresses.","type":"array","items":{"type":"string"},"nullable":true},"notifyCc":{"type":"array","items":{"type":"string"},"nullable":true},"notifyBcc":{"type":"array","items":{"type":"string"},"nullable":true}},"type":"object"},"groups":{"type":"array","items":{"required":["name","order","fields"],"properties":{"id":{"description":"Existing group to keep.","type":"integer","nullable":true},"name":{"type":"string","example":"Contact details"},"order":{"type":"integer","example":1},"startsStep":{"type":"boolean","nullable":true},"stepTitle":{"type":"string","maxLength":255,"nullable":true},"fields":{"type":"array","items":{"properties":{"id":{"description":"Existing field to keep.","type":"integer","nullable":true},"label":{"type":"string","example":"Preferred contact time"},"type":{"type":"string","enum":["text","textarea","number","email","phone","date","time","select","checkbox","toggle","file","radio","group"]},"isRequired":{"type":"boolean","nullable":true},"isVisible":{"type":"boolean","nullable":true},"isArchived":{"type":"boolean","nullable":true},"order":{"type":"integer","example":1},"settings":{"description":"Per-type settings: ui (placeholder, style), validation, options [{label, value}], default, selectType / checkboxType / fileType (single or multiple), maxFileSize, toggleOnLabel / toggleOffLabel, and subFields for a group field.","type":"object","nullable":true}},"type":"object"},"minItems":1}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Form updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"integer","example":1},"version":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":1,"version":2}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:edit","x-fido-module":"forms","x-fido-roles":["admin","scheduler"],"x-fido-area":"Forms","x-fido-area-rank":0}},"/v1/handshake-document-settings":{"get":{"tags":["Handshakes"],"summary":"List handshake document settings","operationId":"ext_get_handshake_document_settings","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Records retrieved successfully.","content":{"application/json":{"schema":{"description":"A paginated list. The envelope carries no message key on this endpoint.","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":4},"documentName":{"type":"string","example":"NDA Agreement"},"isRequired":{"type":"boolean","example":true},"documentUrl":{"description":"Short-lived download link for the attached file, or null when none is attached. Empty outside production.","type":"string","nullable":true},"temporaryUrl":{"description":"The same link as documentUrl.","type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":27}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler","x-fido-area":"Document settings","x-fido-area-rank":1},"post":{"tags":["Handshakes"],"summary":"Create a handshake document setting","operationId":"ext_post_handshake_document_settings","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["document_name"],"properties":{"document_name":{"type":"string","example":"NDA Agreement"},"is_required":{"type":"boolean","example":true},"document":{"description":"File attached to the setting. Send the request as multipart/form-data to attach one.","type":"string","format":"binary","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Record created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Handshake document setting created."},"data":{"properties":{"id":{"type":"integer","example":4},"documentName":{"type":"string","example":"NDA Agreement"},"isRequired":{"type":"boolean","example":true},"documentUrl":{"description":"Short-lived download link for the attached file, or null when none is attached. Empty outside production.","type":"string","nullable":true},"temporaryUrl":{"description":"The same link as documentUrl.","type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"description":"Validation failures use their own envelope — status rather than success, and no code.","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages. Nested keys are collapsed onto the field the form renders.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_notifications_preferences:write","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_notifications_preferences:write`  \n**Roles:** admin, scheduler","x-fido-area":"Document settings","x-fido-area-rank":1}},"/v1/handshake-document-settings/{handshake_document_setting}":{"delete":{"tags":["Handshakes"],"summary":"Delete a handshake document setting","operationId":"ext_delete_handshake_document_settings_By_handshake_document_setting","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"handshake_document_setting","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Record deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Handshake document setting deleted."},"data":{"description":"Not sent on this endpoint.","type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:delete","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_notifications_preferences:delete`  \n**Roles:** admin, scheduler","x-fido-area":"Document settings","x-fido-area-rank":1},"get":{"tags":["Handshakes"],"summary":"Get a handshake document setting by ID","operationId":"ext_get_handshake_document_settings_By_handshake_document_setting","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"handshake_document_setting","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Record retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Handshake document setting retrieved."},"data":{"properties":{"id":{"type":"integer","example":4},"documentName":{"type":"string","example":"NDA Agreement"},"isRequired":{"type":"boolean","example":true},"documentUrl":{"description":"Short-lived download link for the attached file, or null when none is attached. Empty outside production.","type":"string","nullable":true},"temporaryUrl":{"description":"The same link as documentUrl.","type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler","x-fido-area":"Document settings","x-fido-area-rank":1},"post":{"tags":["Handshakes"],"summary":"Update a handshake document setting","operationId":"ext_post_handshake_document_settings_By_handshake_document_setting","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"handshake_document_setting","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"document_name":{"type":"string","example":"Updated NDA"},"is_required":{"type":"boolean","example":false},"document":{"description":"File attached to the setting. Send the request as multipart/form-data to attach one.","type":"string","format":"binary","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Record updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Handshake document setting updated."},"data":{"properties":{"id":{"type":"integer","example":4},"documentName":{"type":"string","example":"NDA Agreement"},"isRequired":{"type":"boolean","example":true},"documentUrl":{"description":"Short-lived download link for the attached file, or null when none is attached. Empty outside production.","type":"string","nullable":true},"temporaryUrl":{"description":"The same link as documentUrl.","type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:edit","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_notifications_preferences:edit`  \n**Roles:** admin, scheduler","x-fido-area":"Document settings","x-fido-area-rank":1}},"/v1/handshake-document-settings/{handshake_document_setting}/document":{"delete":{"tags":["Handshakes"],"summary":"Remove a handshake document setting's attached file","description":"**Required scope:** `settings_notifications_preferences:edit`  \n**Roles:** admin, scheduler\n\nDeletes the attached file and keeps the setting itself.","operationId":"ext_delete_handshake_document_settings_By_handshake_document_setting_document","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"handshake_document_setting","in":"path","required":true,"schema":{"type":"integer","example":4}}],"responses":{"200":{"description":"File removed; returns the updated setting.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Document removed."},"data":{"properties":{"id":{"type":"integer","example":4},"documentName":{"type":"string","example":"NDA Agreement"},"isRequired":{"type":"boolean","example":true},"documentUrl":{"description":"Short-lived download link for the attached file, or null when none is attached. Empty outside production.","type":"string","nullable":true},"temporaryUrl":{"description":"The same link as documentUrl.","type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"400":{"description":"No such setting, or it has no attached file.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:edit","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Document settings","x-fido-area-rank":1}},"/v1/handshakes":{"get":{"tags":["Handshakes"],"summary":"List handshakes for the organization","description":"**Required scope:** `handshakes:read`  \n**Roles:** admin, scheduler\n\nPaginated list of every handshake in the tenant, with optional status, assignment, date-range and free-text filters.","operationId":"ext_get_handshakes","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"status","in":"query","description":"Filter by handshake status.","required":false,"schema":{"type":"string","example":"invited"}},{"name":"assignment_id","in":"query","description":"Only handshakes for this assignment.","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","description":"Free-text search across the selected columns.","required":false,"schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated columns the search applies to.","required":false,"schema":{"type":"string","example":"providerName,status"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Handshakes retrieved.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":27}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:read","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/complete":{"post":{"tags":["Handshakes"],"summary":"Complete a handshake","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nMarks the handshake completed and imports the saved qualifications onto the provider. Rate copying is triggered separately.","operationId":"ext_post_handshakes_By_id_complete","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Handshake completed successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Handshake completed successfully."},"data":{"properties":{"id":{"type":"string","example":"HSK-4KQ2PA"},"assignmentId":{"type":"string","example":"ASG-SA2IVL"},"serviceProviderId":{"type":"string","example":"SPR-H6OUI3"},"status":{"type":"string","example":"offer_sent"},"statusLabel":{"type":"string","example":"Offer Sent"},"rates":{"description":"Negotiated rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"singleRates":{"description":"Negotiated single-rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"messages":{"description":"Message history on the handshake.","type":"array","items":{"type":"object"}},"invitedAt":{"type":"string","format":"date-time","nullable":true},"interestedAt":{"type":"string","format":"date-time","nullable":true},"offerSentAt":{"type":"string","format":"date-time","nullable":true},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declinedBy":{"type":"string","example":"organization","nullable":true},"declineReason":{"type":"string","nullable":true},"invitedByUserId":{"type":"string","example":"USR-9WE3TK","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/documents":{"post":{"tags":["Handshakes"],"summary":"Upload handshake documents (organization)","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nMultipart upload. Each entry may carry a file plus categories, tags and the document setting it satisfies. Documents are stamped as uploaded by the organization.","operationId":"ext_post_handshakes_By_id_documents","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"required":["documents"],"properties":{"documents":{"type":"array","items":{"properties":{"file":{"type":"string","format":"binary"},"id":{"description":"Existing document to keep or update.","type":"integer","nullable":true},"file_name":{"type":"string"},"document_setting_id":{"type":"integer","example":1,"nullable":true},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"type":"object"},"minItems":1}},"type":"object"}}}},"responses":{"201":{"description":"Documents uploaded successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Documents uploaded successfully."},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":18},"documentName":{"type":"string","example":"Signed NDA.pdf"},"documentPath":{"description":"Stored object key.","type":"string","nullable":true},"temporaryUrl":{"description":"The stored object key, as sent today — not a presigned link.","type":"string","nullable":true},"uploadedBy":{"type":"string","enum":["organization","provider"],"example":"organization"},"categories":{"type":"array","items":{"properties":{"id":{"type":"integer","example":3},"value":{"type":"integer","example":3},"label":{"type":"string","example":"Contracts"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"tags":{"type":"array","items":{"properties":{"id":{"type":"integer","example":7},"value":{"type":"integer","example":7},"label":{"type":"string","example":"Onboarding"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed — documents is required.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/documents/{documentId}":{"delete":{"tags":["Handshakes"],"summary":"Delete a handshake document","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nDELETE /handshakes/{id}/documents/{documentId}\nOrg deletes a handshake document.","operationId":"ext_delete_handshakes_By_id_documents_By_documentId","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","description":"Document ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Document deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/missing-services":{"get":{"tags":["Handshakes"],"summary":"Get missing service combinations","description":"**Required scope:** `handshakes:read`  \n**Roles:** admin, scheduler\n\nGET /handshakes/{id}/missing-services","operationId":"ext_get_handshakes_By_id_missing_services","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Missing services data retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Missing services data retrieved successfully."},"data":{"description":"One row per service the provider offers. Empty when the provider record is gone.","type":"array","items":{"properties":{"id":{"description":"Provider service row id.","type":"integer","example":12},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Example label"}},"type":"object"},"hasMissingData":{"description":"True when the handshake still needs details for this service.","type":"boolean","example":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:read","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0},"post":{"tags":["Handshakes"],"summary":"Save missing service combinations","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nRecords service type and provider type pairs the assignment needs but the provider does not yet cover.","operationId":"ext_post_handshakes_By_id_missing_services","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"string"},"providerTypeId":{"type":"string"}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Missing services data saved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Missing services data saved successfully."},"data":{"properties":{"id":{"type":"string","example":"HSK-4KQ2PA"},"assignmentId":{"type":"string","example":"ASG-SA2IVL"},"serviceProviderId":{"type":"string","example":"SPR-H6OUI3"},"status":{"type":"string","example":"offer_sent"},"statusLabel":{"type":"string","example":"Offer Sent"},"rates":{"description":"Negotiated rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"singleRates":{"description":"Negotiated single-rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"messages":{"description":"Message history on the handshake.","type":"array","items":{"type":"object"}},"invitedAt":{"type":"string","format":"date-time","nullable":true},"interestedAt":{"type":"string","format":"date-time","nullable":true},"offerSentAt":{"type":"string","format":"date-time","nullable":true},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declinedBy":{"type":"string","example":"organization","nullable":true},"declineReason":{"type":"string","nullable":true},"invitedByUserId":{"type":"string","example":"USR-9WE3TK","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/notify":{"post":{"tags":["Handshakes"],"summary":"Message the provider","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nSends an in-app notification and optionally a custom email. Supply `message`, or both `emailSubject` and `emailMessage` — the email pair must be sent together.","operationId":"ext_post_handshakes_By_id_notify","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"message":{"description":"In-app message. Required unless an email subject and body are supplied.","type":"string","maxLength":2000,"example":"Request processed successfully.","nullable":true},"emailSubject":{"description":"Required when emailMessage is present.","type":"string","maxLength":255,"nullable":true},"emailMessage":{"description":"Required when emailSubject is present.","type":"string","maxLength":5000,"example":"Request processed successfully.","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Notification sent successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notification sent successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/offer":{"post":{"tags":["Handshakes"],"summary":"Send the provider an offer","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nMoves the handshake into the offer stage using the rates already saved on it, and notifies the provider. Takes no body — set rates first via the rate endpoint.","operationId":"ext_post_handshakes_By_id_offer","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Offer sent successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Offer sent successfully."},"data":{"properties":{"id":{"type":"string","example":"HSK-4KQ2PA"},"assignmentId":{"type":"string","example":"ASG-SA2IVL"},"serviceProviderId":{"type":"string","example":"SPR-H6OUI3"},"status":{"type":"string","example":"offer_sent"},"statusLabel":{"type":"string","example":"Offer Sent"},"rates":{"description":"Negotiated rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"singleRates":{"description":"Negotiated single-rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"messages":{"description":"Message history on the handshake.","type":"array","items":{"type":"object"}},"invitedAt":{"type":"string","format":"date-time","nullable":true},"interestedAt":{"type":"string","format":"date-time","nullable":true},"offerSentAt":{"type":"string","format":"date-time","nullable":true},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declinedBy":{"type":"string","example":"organization","nullable":true},"declineReason":{"type":"string","nullable":true},"invitedByUserId":{"type":"string","example":"USR-9WE3TK","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/org-decline":{"post":{"tags":["Handshakes"],"summary":"Decline a provider","description":"**Required scope:** `handshakes:delete`  \n**Roles:** admin, scheduler\n\nThe organization declines this provider. Terminal for the handshake.","operationId":"ext_post_handshakes_By_id_org_decline","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"reason":{"description":"Optional reason, recorded on the handshake.","type":"string","maxLength":1000,"example":"Client requested a change","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Organization declined provider.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Organization declined provider."},"data":{"properties":{"id":{"type":"string","example":"HSK-4KQ2PA"},"assignmentId":{"type":"string","example":"ASG-SA2IVL"},"serviceProviderId":{"type":"string","example":"SPR-H6OUI3"},"status":{"type":"string","example":"offer_sent"},"statusLabel":{"type":"string","example":"Offer Sent"},"rates":{"description":"Negotiated rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"singleRates":{"description":"Negotiated single-rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"messages":{"description":"Message history on the handshake.","type":"array","items":{"type":"object"}},"invitedAt":{"type":"string","format":"date-time","nullable":true},"interestedAt":{"type":"string","format":"date-time","nullable":true},"offerSentAt":{"type":"string","format":"date-time","nullable":true},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declinedBy":{"type":"string","example":"organization","nullable":true},"declineReason":{"type":"string","nullable":true},"invitedByUserId":{"type":"string","example":"USR-9WE3TK","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:delete","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/provider/{tab}":{"get":{"tags":["Handshakes"],"summary":"Get one tab of the provider detail view","description":"**Required scope:** `handshakes:read`  \n**Roles:** admin, scheduler\n\nBacks the org-side handshake detail page. The response shape differs per tab: `details` and `qualifications` return an object, `documents` returns an array of document groups, and `rates` is paginated.","operationId":"ext_get_handshakes_By_id_provider_By_tab","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}},{"name":"tab","in":"path","description":"Which tab to load.","required":true,"schema":{"type":"string","enum":["details","qualifications","rates","documents"]}},{"name":"serviceType","in":"query","description":"Rates tab only.","required":false,"schema":{"type":"string"}},{"name":"providerType","in":"query","description":"Rates tab only.","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","description":"Rates tab only.","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","description":"Rates tab only.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Rates tab only.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Tab data retrieved.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Tab data retrieved."},"data":{"description":"Shape follows the tab: an object for details and qualifications, an array of document groups for documents, and a paginated payload for rates.","oneOf":[{"type":"object"},{"type":"array","items":{"type":"object"}}]}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Handshake or provider not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"422":{"description":"Unknown tab. Allowed: details, qualifications, rates, documents.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:read","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/qualifications":{"post":{"tags":["Handshakes"],"summary":"Save selected qualifications","description":"**Required scope:** `handshakes:edit`  \n**Roles:** admin, scheduler\n\nRecords which service type and provider type combinations the organization has chosen. These are imported onto the provider when the handshake completes.","operationId":"ext_post_handshakes_By_id_qualifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"qualifications":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"string"},"serviceProviderTypeId":{"type":"string"}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Qualifications saved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Qualifications saved successfully."},"data":{"properties":{"id":{"type":"string","example":"HSK-4KQ2PA"},"assignmentId":{"type":"string","example":"ASG-SA2IVL"},"serviceProviderId":{"type":"string","example":"SPR-H6OUI3"},"status":{"type":"string","example":"offer_sent"},"statusLabel":{"type":"string","example":"Offer Sent"},"rates":{"description":"Negotiated rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"singleRates":{"description":"Negotiated single-rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"messages":{"description":"Message history on the handshake.","type":"array","items":{"type":"object"}},"invitedAt":{"type":"string","format":"date-time","nullable":true},"interestedAt":{"type":"string","format":"date-time","nullable":true},"offerSentAt":{"type":"string","format":"date-time","nullable":true},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declinedBy":{"type":"string","example":"organization","nullable":true},"declineReason":{"type":"string","nullable":true},"invitedByUserId":{"type":"string","example":"USR-9WE3TK","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/rates/{rateId}":{"post":{"tags":["Handshakes"],"summary":"Update one negotiated rate","description":"**Required scope:** `handshakes:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nChanges a single rate's value. Does not advance the handshake status — send an offer separately once the rates are right.","operationId":"ext_post_handshakes_By_id_rates_By_rateId","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}},{"name":"rateId","in":"path","description":"Rate ID on the handshake.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["rate"],"properties":{"rate":{"type":"number","format":"float","minimum":0,"example":85}},"type":"object"}}}},"responses":{"200":{"description":"Rate updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate updated successfully."},"data":{"properties":{"id":{"type":"string","example":"HSK-4KQ2PA"},"assignmentId":{"type":"string","example":"ASG-SA2IVL"},"serviceProviderId":{"type":"string","example":"SPR-H6OUI3"},"status":{"type":"string","example":"offer_sent"},"statusLabel":{"type":"string","example":"Offer Sent"},"rates":{"description":"Negotiated rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"singleRates":{"description":"Negotiated single-rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"messages":{"description":"Message history on the handshake.","type":"array","items":{"type":"object"}},"invitedAt":{"type":"string","format":"date-time","nullable":true},"interestedAt":{"type":"string","format":"date-time","nullable":true},"offerSentAt":{"type":"string","format":"date-time","nullable":true},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declinedBy":{"type":"string","example":"organization","nullable":true},"declineReason":{"type":"string","nullable":true},"invitedByUserId":{"type":"string","example":"USR-9WE3TK","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit finance:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/handshakes/{id}/single-rates/{rateId}":{"post":{"tags":["Handshakes"],"summary":"Update one negotiated single pay rate","description":"**Required scope:** `handshakes:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nChanges the assignment or shift lane of a single pay rate on a handshake. Does not advance the handshake status.","operationId":"ext_post_handshakes_By_id_single_rates_By_rateId","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Handshake ID.","required":true,"schema":{"type":"string"}},{"name":"rateId","in":"path","description":"Single rate ID on the handshake.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Send assignmentRate, shiftRate, or both. With type set, only that lane changes, and its value is read from the matching key, falling back to the other one.","properties":{"assignmentRate":{"type":"number","format":"float","minimum":0,"example":55,"nullable":true},"shiftRate":{"type":"number","format":"float","minimum":0,"example":48,"nullable":true},"type":{"type":"string","enum":["assignment","shift"],"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Single rate updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Single rate updated successfully."},"data":{"properties":{"id":{"type":"string","example":"HSK-4KQ2PA"},"assignmentId":{"type":"string","example":"ASG-SA2IVL"},"serviceProviderId":{"type":"string","example":"SPR-H6OUI3"},"status":{"type":"string","example":"offer_sent"},"statusLabel":{"type":"string","example":"Offer Sent"},"rates":{"description":"Negotiated rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"singleRates":{"description":"Negotiated single-rate rows as stored on the handshake.","type":"array","items":{"type":"object"}},"messages":{"description":"Message history on the handshake.","type":"array","items":{"type":"object"}},"invitedAt":{"type":"string","format":"date-time","nullable":true},"interestedAt":{"type":"string","format":"date-time","nullable":true},"offerSentAt":{"type":"string","format":"date-time","nullable":true},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declinedBy":{"type":"string","example":"organization","nullable":true},"declineReason":{"type":"string","nullable":true},"invitedByUserId":{"type":"string","example":"USR-9WE3TK","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'handshakes:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Neither rate was sent (code missing_rate), or validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"handshakes:edit finance:edit","x-fido-module":"handshakes","x-fido-roles":["admin","scheduler"],"x-fido-area":"Handshakes","x-fido-area-rank":0}},"/v1/identities":{"get":{"tags":["Settings · General"],"summary":"Retrieve paginated identities with optional filters","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of identities. Allows search and sorting. Supports multi-tenancy via X-TENANT-ID header. `isCustom` is false for the default entries, which can't be renamed or deleted.","operationId":"ext_get_identities","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"Veteran"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortBy","in":"query","description":"Field to sort by (defaults to id)","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc, defaults to desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Identities retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Veteran"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":7}},"type":"object"}},"type":"object"}}}},"400":{"description":"The list could not be read.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve.","errors":null,"code":""}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Identities","x-fido-area-rank":6},"post":{"tags":["Settings · General"],"summary":"Create one or more identities","description":"**Required scope:** `settings_general:write`  \n**Roles:** admin, scheduler\n\nAdd custom identities to the organization's list. Entries added here are custom (`isCustom` true) and can be renamed or deleted.","operationId":"ext_post_identities","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"description":"One or more entries to add. Multipart requests may send it as a JSON string.","type":"array","items":{"required":["label"],"properties":{"label":{"type":"string","maxLength":255,"example":"Late-deafened"}},"type":"object"}}},"type":"object"}}}},"responses":{"201":{"description":"Identity created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Custom identity Late-deafened (10) has been saved successfully."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed (missing name, a name already on the list in any case, or the same name given twice in one request).","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn't save this identity. Correct the highlighted fields and try again."},"errors":{"description":"Messages keyed by the field they belong to; every entry's message lands on `name`.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"},"example":{"status":"error","message":"We couldn't save this identity. Correct the highlighted fields and try again.","errors":{"name":["This identity already exists."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Identities","x-fido-area-rank":6}},"/v1/identities/{identity}":{"delete":{"tags":["Settings · General"],"summary":"Delete a custom identity","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nArchive a custom identity by ID. Default entries (`isCustom` false) can't be deleted.","operationId":"ext_delete_identities_By_identity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"identity","in":"path","description":"ID of the identity to delete.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Identity deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Custom identity Late-deafened (10) was deleted successfully."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"400":{"description":"The entry is a default, or archived.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Default identities can't be deleted."},"errors":{"type":"string","example":"Failed to delete."},"code":{"type":"string","example":""}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"An unknown id.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields","errors":{"id":["Identity not found."]},"code":""}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Identities","x-fido-area-rank":6},"get":{"tags":["Settings · General"],"summary":"Retrieve an identity by ID","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch an identity by its ID.","operationId":"ext_get_identities_By_identity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"identity","in":"path","description":"ID of the identity to retrieve.","required":true,"schema":{"type":"integer","example":6}}],"responses":{"200":{"description":"Identity retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Identity retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":6},"value":{"type":"integer","example":6},"label":{"type":"string","example":"Veteran"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"400":{"description":"No active entry with that id.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Identity not found."},"errors":{"type":"string","example":"Failed to retrieve."},"code":{"type":"string","example":""}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"The id is not a number (the route only matches numeric ids).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The route api/v1/identities/abc could not be found."},"errors":{"type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Identities","x-fido-area-rank":6},"put":{"tags":["Settings · General"],"summary":"Rename a custom identity","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nRename a custom identity by ID. Default entries (`isCustom` false) can't be renamed.","operationId":"ext_put_identities_By_identity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"identity","in":"path","description":"ID of the identity to update.","required":true,"schema":{"type":"integer","example":10}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Late-deafened community"}},"type":"object"}}}},"responses":{"200":{"description":"Identity updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to custom identity Late-deafened community (10) were saved."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"An unknown id, or a missing or taken name (the form shape, with `status`); or an archived entry or a default (the envelope, with `success`).","content":{"application/json":{"schema":{"oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn't save this identity. Correct the highlighted fields and try again."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"type":"object","additionalProperties":{"type":"string"}},"code":{"type":"string","example":""}},"type":"object"}]},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields","errors":{"name":"Default identities can't be renamed."},"code":""}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Identities","x-fido-area-rank":6},"patch":{"tags":["Settings · General"],"summary":"Rename a custom identity","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nRename a custom identity by ID. Default entries (`isCustom` false) can't be renamed.","operationId":"ext_patch_identities_By_identity","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"identity","in":"path","description":"ID of the identity to update.","required":true,"schema":{"type":"integer","example":10}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Late-deafened community"}},"type":"object"}}}},"responses":{"200":{"description":"Identity updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to custom identity Late-deafened community (10) were saved."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"An unknown id, or a missing or taken name (the form shape, with `status`); or an archived entry or a default (the envelope, with `success`).","content":{"application/json":{"schema":{"oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn't save this identity. Correct the highlighted fields and try again."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"type":"object","additionalProperties":{"type":"string"}},"code":{"type":"string","example":""}},"type":"object"}]},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields","errors":{"name":"Default identities can't be renamed."},"code":""}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Something went wrong!","errors":null,"code":""}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Identities","x-fido-area-rank":6}},"/v1/industries":{"get":{"tags":["Settings · General"],"summary":"Retrieve all industries or filter by tenant ID","description":"**Required scope:** `settings_general:read`\n\nFetch a list of all industries or filter by a specific tenant ID if provided.","operationId":"ext_get_industries","parameters":[{"name":"tenantId","in":"query","description":"Tenant ID. Used for multi-tenant filtering.","required":false,"schema":{"type":"string","example":"demotenant"}}],"responses":{"200":{"description":"Industries retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Industries Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Industries Retrieved!","data":[{"id":1,"value":1,"label":"Example label","isCustom":true}]}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Industries","x-fido-area-rank":3},"post":{"tags":["Settings · General"],"summary":"Create a new industry","description":"**Required scope:** `settings_general:write`\n\nCreate a new industry with a name and optional tenant ID.","operationId":"ext_post_industries","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","tenant_id"],"properties":{"name":{"type":"string","example":"Tech Industry"},"tenant_id":{"type":"string","example":"demotenant"}},"type":"object"}}}},"responses":{"201":{"description":"Industry created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Industry created!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Industry created!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Industries","x-fido-area-rank":3}},"/v1/industries/{id}/{label}":{"delete":{"tags":["Settings · General"],"summary":"Delete an industry","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete an industry by its ID.","operationId":"ext_delete_industries_By_id_By_label","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"ID of the industry to delete.","required":true,"schema":{"type":"integer","example":7}},{"name":"label","in":"path","description":"Label of the industry to delete.","required":true,"schema":{"type":"string","example":"industry"}}],"responses":{"200":{"description":"Industry deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Industry deleted!"}},"type":"object"},"example":{"success":true,"message":"Industry deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Industry not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Industry with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Industry with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Industries","x-fido-area-rank":3}},"/v1/industries/{industry}":{"delete":{"tags":["Settings · General"],"summary":"Delete an industry by id alone (always 422)","description":"**Required scope:** `settings_general:delete`\n\n**Use `/v1/industries/{id}/{label}` instead.** This id-only form is registered by the resource route, but the handler identifies the record from a `label` path segment this route does not carry, so the call always fails validation with `label` required.","operationId":"ext_delete_industries_By_industry","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"industry","in":"path","description":"ID of the industry.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed: the industry type could not be resolved from the URL.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The label field is required."}},"type":"object"},"example":{"status":"error","message":"The label field is required."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Industries","x-fido-area-rank":3},"get":{"tags":["Settings · General"],"summary":"Retrieve a single industry (not implemented)","description":"**Required scope:** `settings_general:read`\n\n**Not implemented.** The route is registered, but the controller action has no body, so the call succeeds with an empty response and no `{success, message, data}` envelope. Read the industry from the list endpoint `/v1/industries` instead.","operationId":"ext_get_industries_By_industry","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"industry","in":"path","description":"ID of the industry.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Empty body — the action is not implemented."},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Industries","x-fido-area-rank":3},"put":{"tags":["Settings · General"],"summary":"Update an industry","description":"**Required scope:** `settings_general:edit`\n\nUpdate an industry by ID.","operationId":"ext_put_industries_By_industry","parameters":[{"name":"industry","in":"path","description":"ID of the industry to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Tech Industry"}},"type":"object"}}}},"responses":{"200":{"description":"Industry updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Industry updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Industry updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Industry not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Industry with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Industry with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Industries","x-fido-area-rank":3},"patch":{"tags":["Settings · General"],"summary":"Update an industry","description":"**Required scope:** `settings_general:edit`\n\nUpdate an industry by ID.","operationId":"ext_patch_industries_By_industry","parameters":[{"name":"industry","in":"path","description":"ID of the industry to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Tech Industry"}},"type":"object"}}}},"responses":{"200":{"description":"Industry updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Industry updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Industry updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Industry not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Industry with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Industry with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Industries","x-fido-area-rank":3}},"/v1/insurances":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve all insurances or filter by tenant ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of insurances with search, filters, sorting and pagination. Each row carries the service type and service provider type it is for.","operationId":"ext_get_insurances","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant filtering.","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Matches the start of any word in the insurance name, its service type name or its service provider type name, in any case.","required":false,"schema":{"type":"string","example":"Liability"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to apply search on (e.g., name).","required":false,"schema":{"type":"string","example":"name"}},{"name":"insuranceId","in":"query","description":"Filter by specific insurance ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"serviceType","in":"query","description":"Filter by service type ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"serviceProviderType","in":"query","description":"Filter by service provider type ID.","required":false,"schema":{"type":"integer","example":2}},{"name":"requirement","in":"query","description":"Filter by requirement level.","required":false,"schema":{"type":"string","enum":["required","preferred","optional"],"example":"preferred"}},{"name":"expirationRequired","in":"query","description":"Filter insurances based on whether expiration is required.","required":false,"schema":{"type":"boolean","example":true}},{"name":"uploadRequired","in":"query","description":"Filter insurances based on whether document upload is required.","required":false,"schema":{"type":"boolean","example":true}},{"name":"sortBy","in":"query","description":"Field to sort by: name, serviceType, serviceProviderType, requirement, expirationRequired, uploadRequired or a column name. Defaults to id.","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sort order: asc or desc (the default; anything other than asc reads as desc).","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of results per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number.","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Insurances retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"General Liability"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object","nullable":true},"serviceProviderType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Hearing Interpreter"}},"type":"object","nullable":true},"requirement":{"type":"string","example":"preferred"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"name":"General Liability","serviceType":{"id":1,"label":"ASL"},"serviceProviderType":{"id":2,"label":"Hearing Interpreter"},"requirement":"preferred","expirationRequired":true,"uploadRequired":true}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":1}}}}},"400":{"description":"An unknown sort column or a non-numeric id filter.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"description":"The underlying error, in debug mode only.","type":"string","nullable":true},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve.","errors":null,"code":""}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Insurances","x-fido-area-rank":5},"post":{"tags":["Settings · Service Setup"],"summary":"Create new insurances","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate one or more insurances, one per name, all for the service type and service provider type sent. A name must not already be on the list for that pair, in any case, nor be given twice.","operationId":"ext_post_insurances","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["serviceType","serviceProviderType","name","requirement"],"properties":{"serviceType":{"required":["id"],"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"description":"One of the service type's provider types.","required":["id"],"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Hearing Interpreter"}},"type":"object"},"name":{"type":"array","items":{"required":["label"],"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"General Liability"}},"type":"object"}},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"preferred"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}}}},"responses":{"201":{"description":"Insurance(s) created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Insurance General Liability has been saved successfully."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"},"example":{"success":true,"message":"Insurance General Liability has been saved successfully.","data":null}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed. Errors are keyed by the field the form shows: name, serviceType, serviceProviderType or requirement.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn’t save this insurance. Correct the highlighted fields and try again."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Insurance Name is already taken."}},"serviceProviderType":{"type":"array","items":{"type":"string","example":"Invalid Service Provider Type selected."}}},"type":"object"}},"type":"object"},"example":{"status":"error","message":"We couldn’t save this insurance. Correct the highlighted fields and try again.","errors":{"name":["Insurance Name is already taken."],"serviceProviderType":["Invalid Service Provider Type selected."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Insurances","x-fido-area-rank":5}},"/v1/insurances/{insurance}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete an insurance","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nSoft-delete an insurance by ID. Its name can then be added again for the same service type and service provider type.","operationId":"ext_delete_insurances_By_insurance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"insurance","in":"path","description":"ID of the insurance to delete.","required":true,"schema":{"type":"integer","example":5}}],"responses":{"200":{"description":"Insurance deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Insurance General Liability (5) was deleted successfully."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"},"example":{"success":true,"message":"Insurance General Liability (5) was deleted successfully.","data":null}}}},"400":{"description":"Insurance not found (unknown or already deleted).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Insurance with ID 5 not found."},"errors":{"type":"string","example":"Failed to delete."},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Insurance with ID 5 not found.","errors":"Failed to delete.","code":""}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Insurances","x-fido-area-rank":5},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a specific insurance by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a single insurance record by its ID, in the shape the edit dialog reads.","operationId":"ext_get_insurances_By_insurance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"insurance","in":"path","description":"ID of the insurance to retrieve.","required":true,"schema":{"type":"integer","example":3}}],"responses":{"200":{"description":"Insurance retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Insurance Retrieved!"},"data":{"properties":{"id":{"type":"integer","example":3},"name":{"properties":{"id":{"type":"integer","example":3},"label":{"type":"string","example":"General Liability"}},"type":"object"},"isCustom":{"type":"boolean","example":null,"nullable":true},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object","nullable":true},"serviceProviderType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Hearing Interpreter"}},"type":"object","nullable":true},"requirement":{"type":"string","example":"preferred"},"expirationRequired":{"type":"boolean","example":true},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Insurance Retrieved!","data":{"id":3,"name":{"id":3,"label":"General Liability"},"isCustom":null,"serviceType":{"id":1,"label":"ASL"},"serviceProviderType":{"id":2,"label":"Hearing Interpreter"},"requirement":"preferred","expirationRequired":true,"uploadRequired":true}}}}},"400":{"description":"Insurance not found (unknown or deleted).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Insurance with ID 3 not found."},"errors":{"type":"string","example":"Failed to retrieve."},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Insurance with ID 3 not found.","errors":"Failed to retrieve.","code":""}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Insurances","x-fido-area-rank":5},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing insurance","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nChange the fields sent: name, requirement, expirationRequired, uploadRequired. The service type and service provider type can't be changed. A name must not be on the list already for the entry's own service type and provider type; the entry may keep its own name in another case.","operationId":"ext_put_insurances_By_insurance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"insurance","in":"path","description":"ID of the insurance to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"General Liability"},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"required"},"expirationRequired":{"type":"boolean","example":false},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}}}},"responses":{"200":{"description":"Insurance updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to Insurance General Liability (3) were saved."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"},"example":{"success":true,"message":"Changes to Insurance General Liability (3) were saved.","data":null}}}},"400":{"description":"Insurance not found (unknown or deleted).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Insurance with ID 3 not found."},"errors":{"type":"string","example":"Failed to update."},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Insurance with ID 3 not found.","errors":"Failed to update.","code":""}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn’t save this insurance. Correct the highlighted fields and try again."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Insurance Name is already taken."}}},"type":"object"}},"type":"object"},"example":{"status":"error","message":"We couldn’t save this insurance. Correct the highlighted fields and try again.","errors":{"name":["Insurance Name is already taken."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Insurances","x-fido-area-rank":5},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing insurance","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nChange the fields sent: name, requirement, expirationRequired, uploadRequired. The service type and service provider type can't be changed. A name must not be on the list already for the entry's own service type and provider type; the entry may keep its own name in another case.","operationId":"ext_patch_insurances_By_insurance","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"insurance","in":"path","description":"ID of the insurance to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"General Liability"},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"required"},"expirationRequired":{"type":"boolean","example":false},"uploadRequired":{"type":"boolean","example":true}},"type":"object"}}}},"responses":{"200":{"description":"Insurance updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to Insurance General Liability (3) were saved."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"},"example":{"success":true,"message":"Changes to Insurance General Liability (3) were saved.","data":null}}}},"400":{"description":"Insurance not found (unknown or deleted).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Insurance with ID 3 not found."},"errors":{"type":"string","example":"Failed to update."},"code":{"type":"string","example":""}},"type":"object"},"example":{"success":false,"message":"Insurance with ID 3 not found.","errors":"Failed to update.","code":""}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"We couldn’t save this insurance. Correct the highlighted fields and try again."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Insurance Name is already taken."}}},"type":"object"}},"type":"object"},"example":{"status":"error","message":"We couldn’t save this insurance. Correct the highlighted fields and try again.","errors":{"name":["Insurance Name is already taken."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Insurances","x-fido-area-rank":5}},"/v1/locations":{"get":{"tags":["Clients"],"summary":"Retrieve a list of  locations","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of client locations based on filters like search, client, location, sorting, etc.","operationId":"ext_get_locations","parameters":[{"name":"search","in":"query","required":false,"schema":{"description":"Search query to filter locations by name, address, city, etc.","type":"string"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"client","in":"query","required":false,"schema":{"description":"Filter locations by associated client name or email.","type":"string"}},{"name":"location","in":"query","required":false,"schema":{"description":"Filter locations by location name.","type":"string"}},{"name":"columns","in":"query","required":false,"schema":{"description":"Search query within visible column content.","type":"string","example":"clientName,address,contact,status"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter locations created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter locations created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"sortBy","in":"query","required":false,"schema":{"description":"Sort locations by a specific field (e.g., 'name', 'created_at').","type":"string"}},{"name":"sortOrder","in":"query","required":false,"schema":{"description":"Sorting order: ascending ('asc') or descending ('desc').","type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","required":false,"schema":{"description":"Number of locations to retrieve per page.","type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"description":"Page number to retrieve.","type":"integer","example":1}},{"name":"status","in":"query","required":false,"schema":{"description":"Filter locations by status ID.","type":"integer"}},{"name":"isPublished","in":"query","required":false,"schema":{"description":"Filter locations by their Published status.","type":"boolean"}}],"responses":{"200":{"description":"Locations retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ORGLOC-J16XA"},"locationName":{"type":"string","example":"Main Office"},"logo":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"addressLine1":{"type":"string","example":"123 Main St","nullable":true},"addressLine2":{"type":"string","example":"Suite 200","nullable":true},"city":{"type":"string","example":"Austin","nullable":true},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"code":{"type":"string"}},"type":"object","nullable":true},"postalCode":{"type":"string","example":"90210","nullable":true},"accessInstruction":{"type":"string","nullable":true},"status":{"type":"integer","example":1,"nullable":true},"statusName":{"type":"string","example":"Active","nullable":true},"department":{"type":"string","example":"Radiology","nullable":true},"contactName":{"type":"string","example":"Jane Smith","nullable":true},"contactImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"contactEmail":{"type":"string","example":"user@example.com","nullable":true},"contactPhone":{"type":"string","example":"+1-555-0142","nullable":true},"contactPhoneExtension":{"type":"string","example":"101","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"client":{"type":"string","example":"CLT-XWB2RY"},"clientName":{"type":"string","example":"Example name","nullable":true},"clientImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"onlineStatus":{"type":"string","example":"online"},"clientEmail":{"type":"string","example":"user@example.com","nullable":true},"clientPhone":{"type":"string","example":"+1-555-0142","nullable":true},"clientType":{"type":"string","example":"Individual","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"isPrimaryAddress":{"type":"boolean","example":true},"isPublished":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"},"example":{"success":false,"message":"Invalid parameters. Ensure all required filters are correct."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/locations/document/files":{"delete":{"tags":["Clients"],"summary":"Delete files associated with an client location","description":"**Required scope:** `clients:edit`  \n**Roles:** admin, client, scheduler\n\nDeletes uploaded files tied to an client location.","operationId":"ext_delete_locations_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["fileIds"],"properties":{"fileIds":{"description":"Array of document file IDs","type":"array","items":{"type":"integer","example":1}}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully!"}},"type":"object"},"example":{"success":true,"message":"Files deleted successfully!"}}}},"400":{"description":"Bad request - Missing or invalid file ID","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid file ID(s) provided."}},"type":"object"},"example":{"success":false,"message":"Invalid file ID(s) provided."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"A client-portal caller attempted to delete a document that isn't theirs, or referenced a document id that doesn't resolve. The message is deliberately generic and does not distinguish the two.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:edit","x-fido-module":"clients","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/locations/export":{"get":{"tags":["Clients"],"summary":"Export locations to Excel","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all locations to an Excel file for download.","operationId":"ext_get_locations_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-NRLWQEDM"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing all clients","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/locations/name-list":{"get":{"tags":["Clients"],"summary":"Get all locations' names and IDs","description":"**Required scope:** `clients:read`  \n**Roles:** admin, scheduler\n\nFetches a list of all locations with only their ID and name.","operationId":"ext_get_locations_name_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"List of locations retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Locations fetched successfully!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"New York"}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Locations fetched successfully!","data":[{"id":1,"name":"New York"},{"id":2,"name":"San Francisco"}]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/locations/{client}":{"get":{"tags":["Clients"],"summary":"Retrieve all locations for a specific client","description":"**Required scope:** `clients:read` or `assignments:read` or `shifts:read` or `schedule:read` or `consumers:read` or `providers:read` or `finance:read` or `forms:read`\n\nFetches all locations associated with the specified client ID, returning their basic details like label, address, and primary flag.","operationId":"ext_get_locations_By_client","parameters":[{"name":"client","in":"path","description":"Unique identifier of the client","required":true,"schema":{"type":"string","example":"CLT-EDFFGJ"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"isPublished","in":"query","description":"Filter locations by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"isActive","in":"query","description":"Filter locations by their Active status.","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"Client Location details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client Location details retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLTLOC-HQBS7"},"label":{"type":"string","example":"Example label"},"addressLine1":{"type":"string","example":"123 Main St"},"addressLine2":{"type":"string","example":"Suite 200"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"code":{"type":"string","example":"string"}},"type":"object"},"postalCode":{"type":"string","example":"90210"},"isPrimary":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Client Location details retrieved!","data":[{"id":"CLTLOC-HQBS7","label":"Example label","addressLine1":"123 Main St","addressLine2":"Suite 200","city":"Austin","state":{"id":1,"label":"Example label","code":"string"},"postalCode":"90210","isPrimary":true,"isDefault":true}]}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid Client ID","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Client ID is required."},"errors":{"type":"string","nullable":true}},"type":"object"},"example":{"success":false,"message":"Client ID is required.","errors":null}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"SQLSTATE[HY000]: General error: 1234 Something went wrong","nullable":true}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred — please try again.","errors":"SQLSTATE[HY000]: General error: 1234 Something went wrong"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read|assignments:read|shifts:read|schedule:read|consumers:read|providers:read|finance:read|forms:read","x-fido-module":"clients","x-fido-roles":[],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/organization-location":{"post":{"tags":["Settings · Organization Locations"],"summary":"Create a new organization location","description":"**Required scope:** `settings_locations:write`  \n**Roles:** admin, scheduler\n\nCreates a new organization location with the provided details, including skills, certifications, and specializations. Rates & Billing fields (rates, single rates, admin fee, billing and cancellation terms) need Finance Write: without it they are left out and the new record takes the organization's.","operationId":"ext_post_organization_location","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"description":"Name of the organization Location","type":"string","example":"Location 1"},"description":{"description":"Brief description of the organization location","type":"string","example":"This is a demo tenant for showcasing purposes.","nullable":true},"logo":{"description":"Organization Location Logo","type":"string","example":null,"nullable":true},"department":{"description":"Enter organization departments OR units","type":"string","example":"Test"},"contactImage":{"description":"Organization's contact person image","type":"string","example":null,"nullable":true},"contactName":{"description":"Organization's contact name","type":"string","format":"string","example":"Contact Name"},"contactEmail":{"description":"Organization's contact email","type":"string","format":"email","example":"contact@demotenant.com"},"role":{"description":"contact person role","type":"string","example":"Role","nullable":true},"countryCode":{"description":"Organization's contact phone country code","type":"string","example":"+1","nullable":true},"phone":{"description":"Organization's contact phone number","type":"string","example":"9888888888","nullable":true},"videoPhoneCountryCode":{"description":"Video phone country code","type":"string","example":"+1","nullable":true},"videoPhone":{"description":"Video phone number","type":"string","example":"9888888888","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gender":{"description":"Required when the location is published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"priority":{"description":"Default priority for work at this location.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"phoneType":{"description":"Organization's contact phone type","type":"string","example":"voice_only","nullable":true},"addressLine1":{"description":"Enter street address line1.","type":"string","example":"addressLine1"},"addressLine2":{"description":"Enter street address line2.","type":"string","example":"addressLine2","nullable":true},"city":{"description":"Enter organization location city","type":"string","example":"City"},"state":{"description":"Organization location state","properties":{"id":{"type":"integer","example":8},"label":{"type":"string","example":"Delaware"}},"type":"object"},"postalCode":{"description":"Enter organization location postal code","type":"string","example":"12345"},"accessInstruction":{"description":"Enter organization location access instructions","type":"string","example":"Access instructions text"},"skills":{"description":"Skills associated with the organization location, including predefined and custom skills","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Skill1"},{"id":2,"label":"Skill2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"certifications":{"description":"Certifications associated with the organization location","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Certifications1"},{"id":2,"label":"Certifications2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"clearances":{"description":"Security clearances assigned to the organization location","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Clearances1"},{"id":2,"label":"Clearances2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"specializations":{"description":"Specializations assigned to the organization location","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Specializations1"},{"id":2,"label":"Specializations2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"internalNotes":{"description":"Internal notes for administrators","type":"string","example":"Confidential information regarding tenant.","nullable":true},"status":{"description":"Status of the location. Required when publishing.","properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"phoneExtension":{"type":"string","example":"204","nullable":true},"timezone":{"description":"IANA timezone of the location","type":"string","example":"America/New_York","nullable":true},"shiftCapacity":{"description":"The location tracks shift capacity","type":"boolean","example":false,"nullable":true},"minimumCapacity":{"description":"Must not exceed maximumCapacity","type":"integer","minimum":0,"example":1,"nullable":true},"maximumCapacity":{"description":"Must be at least minimumCapacity","type":"integer","minimum":1,"example":10,"nullable":true},"isPublished":{"description":"Publishing makes the address, contact and status fields required","type":"boolean","example":true},"enableCustomRates":{"type":"boolean","example":false,"nullable":true},"requireVerifiedTimeDocumentation":{"type":"boolean","example":false,"nullable":true},"customizeRequirementPreferences":{"type":"boolean","example":false,"nullable":true},"adminFee":{"type":"number","format":"float","example":5,"nullable":true},"adminFeeMethod":{"description":"Defaults to flat","type":"string","example":"flat","nullable":true},"adminFeeType":{"description":"What the admin fee applies to","type":"string","enum":["assignment","shift","both"],"example":"assignment","nullable":true},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"}},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"}},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"}},"reimbursableExpenses":{"description":"Reimbursable expenses offered at this location, by id. Ones not sent are removed.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"requirementAndPreferences":{"type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"}},"isDuplicated":{"description":"Set when this create duplicates an existing location; records a duplication audit event instead of a plain create","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The location being duplicated. Read only with isDuplicated=true","type":"string","example":"ORGLOC-123ET","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Organization location created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Organization location created successfully"},"data":{"properties":{"id":{"type":"string","example":"ORGLOC-123ET"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Organization location created successfully","data":{"id":"ORGLOC-123ET"}}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Organization location name is required."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Organization location name is required."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Organization location name is required.","errors":{"name":["Organization location name is required."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:write","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/organization-location/document/files":{"delete":{"tags":["Settings · Organization Locations"],"summary":"Delete files associated with an organization","description":"**Required scope:** `settings_locations:edit`  \n**Roles:** admin, scheduler\n\nDeletes uploaded files tied to an organization.","operationId":"ext_delete_organization_location_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["fileIds"],"properties":{"fileIds":{"description":"Array of document file IDs","type":"array","items":{"type":"integer","example":1}}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully!"}},"type":"object"},"example":{"success":true,"message":"Files deleted successfully!"}}}},"400":{"description":"Bad request - Missing or invalid file ID","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid file ID(s) provided."}},"type":"object"},"example":{"success":false,"message":"Invalid file ID(s) provided."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:edit","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/organization-location/{id}":{"delete":{"tags":["Settings · Organization Locations"],"summary":"Delete organization location","description":"**Required scope:** `settings_locations:delete`  \n**Roles:** admin, scheduler\n\nDelete organization location.","operationId":"ext_delete_organization_location_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"path","description":"ID of the organization to be deleted","required":true,"schema":{"type":"string","example":"ORGLOC-1RED2"}}],"responses":{"200":{"description":"Organization location deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Organization location deleted successfully!"}},"type":"object"},"example":{"success":true,"message":"Organization location deleted successfully!"}}}},"400":{"description":"Bad request - Missing or invalid organization Location ID","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid Organization Location ID provided."}},"type":"object"},"example":{"success":false,"message":"Invalid Organization Location ID provided."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:delete","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0},"post":{"tags":["Settings · Organization Locations"],"summary":"Update an existing organization location","description":"**Required scope:** `settings_locations:edit`  \n**Roles:** admin, scheduler\n\nUpdate an organization location with the provided details, including skills, certifications, and specializations.","operationId":"ext_post_organization_location_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"path","description":"ID of the organization location to update","required":true,"schema":{"type":"string","example":"ORGLOC-1RED2"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"description":"Name of the organization Location","type":"string","example":"Location 1"},"description":{"description":"Brief description of the organization location","type":"string","example":"This is a demo tenant for showcasing purposes.","nullable":true},"logo":{"description":"Organization Location Logo","type":"string","example":null,"nullable":true},"department":{"description":"Enter organization departments OR units","type":"string","example":"Test"},"contactImage":{"description":"Organization's contact person image","type":"string","example":null,"nullable":true},"contactName":{"description":"Organization's contact name","type":"string","format":"string","example":"Contact Name"},"contactEmail":{"description":"Organization's contact email","type":"string","format":"email","example":"contact@demotenant.com"},"role":{"description":"contact person role","type":"string","example":"Role","nullable":true},"countryCode":{"description":"Organization's contact phone country code","type":"string","example":"+1","nullable":true},"phone":{"description":"Organization's contact phone number","type":"string","example":"9888888888","nullable":true},"videoPhoneCountryCode":{"description":"Video phone country code","type":"string","example":"+1","nullable":true},"videoPhone":{"description":"Video phone number","type":"string","example":"9888888888","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gender":{"description":"Required when the location is published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"priority":{"description":"Default priority for work at this location.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"phoneType":{"description":"Organization's contact phone type","type":"string","example":"voice_only","nullable":true},"addressLine1":{"description":"Enter street address line1.","type":"string","example":"addressLine1"},"addressLine2":{"description":"Enter street address line2.","type":"string","example":"addressLine2","nullable":true},"city":{"description":"Enter organization location city","type":"string","example":"City"},"state":{"description":"Organization location state","properties":{"id":{"type":"integer","example":8},"label":{"type":"string","example":"Delaware"}},"type":"object"},"postalCode":{"description":"Enter organization location postal code","type":"string","example":"12345"},"accessInstruction":{"description":"Enter organization location access instructions","type":"string","example":"Access instructions text"},"skills":{"description":"Skills associated with the organization location, including predefined and custom skills","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Skill1"},{"id":2,"label":"Skill2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"certifications":{"description":"Certifications associated with the organization location","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Certifications1"},{"id":2,"label":"Certifications2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"clearances":{"description":"Security clearances assigned to the organization location","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Clearances1"},{"id":2,"label":"Clearances2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"specializations":{"description":"Specializations assigned to the organization location","type":"array","items":{"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Custom1"}},"type":"object"},"example":[{"id":1,"label":"Specializations1"},{"id":2,"label":"Specializations2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}]},"internalNotes":{"description":"Internal notes for administrators","type":"string","example":"Confidential information regarding tenant.","nullable":true},"status":{"description":"Status of the location. Required when publishing.","properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"phoneExtension":{"type":"string","example":"204","nullable":true},"timezone":{"description":"IANA timezone of the location","type":"string","example":"America/New_York","nullable":true},"shiftCapacity":{"description":"The location tracks shift capacity","type":"boolean","example":false,"nullable":true},"minimumCapacity":{"description":"Must not exceed maximumCapacity","type":"integer","minimum":0,"example":1,"nullable":true},"maximumCapacity":{"description":"Must be at least minimumCapacity","type":"integer","minimum":1,"example":10,"nullable":true},"isPublished":{"description":"Publishing makes the address, contact and status fields required","type":"boolean","example":true},"enableCustomRates":{"type":"boolean","example":false,"nullable":true},"requireVerifiedTimeDocumentation":{"type":"boolean","example":false,"nullable":true},"customizeRequirementPreferences":{"type":"boolean","example":false,"nullable":true},"adminFee":{"type":"number","format":"float","example":5,"nullable":true},"adminFeeMethod":{"description":"Defaults to flat","type":"string","example":"flat","nullable":true},"adminFeeType":{"description":"What the admin fee applies to","type":"string","enum":["assignment","shift","both"],"example":"assignment","nullable":true},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"}},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"}},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"}},"reimbursableExpenses":{"description":"Reimbursable expenses offered at this location, by id. Ones not sent are removed.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"requirementAndPreferences":{"type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Organization location updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Organization location updated successfully"},"data":{"properties":{"id":{"type":"string","example":"ORGLOC-123ET"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Organization location updated successfully","data":{"id":"ORGLOC-123ET"}}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The payload carries a Rates & Billing field (rates, single rates, admin fee, billing and cancellation terms) and the role has no Finance Edit, so nothing is saved. A payload without those fields follows the record's own permission alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters. A rate unit other than Per Hour or Per Minute (for example weekly) in a rate or single-rate row is refused and nothing is saved: the same 422 body with errors.unit, errors.assignmentRateUnit or errors.shiftRateUnit (no row index).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Organization location name is required."},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"Organization location name is required."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Organization location name is required.","errors":{"name":["Organization location name is required."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:edit","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/organization-location/{id}/{tab}":{"get":{"tags":["Settings · Organization Locations"],"summary":"Retrieve specific tab details of an organization location","description":"**Required scope:** `settings_locations:read`  \n**Roles:** admin, scheduler\n\nFetches the details for a specific tab within an organization, based on the provided organization ID and tab identifier.","operationId":"ext_get_organization_location_By_id_By_tab","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"path","description":"Unique identifier of the organization location","required":true,"schema":{"type":"string","example":"ORGLOC-4GVGJ"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'general', 'requirement_preferences', 'domain_information', 'document_notes','requirementAndPreferences')","required":true,"schema":{"type":"string","enum":["general","requirement_preferences","rates_billing","document_notes","requirementAndPreferences"],"example":"general"}}],"responses":{"200":{"description":"Organization location retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"string","example":"ORG-MARH4E"},"name":{"type":"string","example":"Demo Tenant"},"description":{"type":"string","example":"This is a demo tenant for showcasing purposes."},"logo":{"type":"string","nullable":true},"department":{"type":"string","example":"Test"},"contactImage":{"type":"string","nullable":true},"contactName":{"type":"string","example":"Contact Name"},"contactEmail":{"type":"string","example":"user@example.com"},"contactRole":{"type":"string","example":"Role"},"contactPhone":{"type":"string","example":"+1-234-567-8900"},"contactPhoneType":{"type":"string","example":"voice_only"},"addressLine1":{"type":"string","example":"addressLine1"},"addressLine2":{"type":"string","example":"addressLine2"},"city":{"type":"string","example":"City"},"state":{"type":"string","example":"State"},"postalCode":{"type":"string","example":"12345"},"accessInstruction":{"type":"string","example":"Access instructions text"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":"ORG-MARH4E","name":"Demo Tenant","description":"This is a demo tenant for showcasing purposes.","logo":null,"department":"Test","contactImage":null,"contactName":"Contact Name","contactEmail":"user@example.com","contactRole":"Role","contactPhone":"+1-234-567-8900","contactPhoneType":"voice_only","addressLine1":"addressLine1","addressLine2":"addressLine2","city":"City","state":"State","postalCode":"12345","accessInstruction":"Access instructions text"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The rates_billing tab is Finances data, so a role without Finance Read is refused it whatever it holds on the record's own module. Every other tab follows the record's module alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified organization does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified organization does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:read","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/organization-locations":{"get":{"tags":["Settings · Organization Locations"],"summary":"Retrieve a list of organization locations","description":"**Required scope:** `settings_locations:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of organization locations based on search criteria, filters, and sorting options.","operationId":"ext_get_organization_locations","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"search","in":"query","required":false,"schema":{"description":"Search query to filter organization locations by name or other attributes.","type":"string","example":null}},{"name":"columns","in":"query","required":false,"schema":{"description":"Search query within visible column content.","type":"string","example":"name,department,status,contactName,contactEmail,addressLine1"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter organizations created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter organizations created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"sortBy","in":"query","required":false,"schema":{"description":"Sort organizations by a specific field (e.g., 'name', 'created_at').","type":"string","example":null}},{"name":"sortOrder","in":"query","required":false,"schema":{"description":"Sorting order: ascending ('asc') or descending ('desc').","type":"string","enum":["asc","desc"],"example":null}},{"name":"perPage","in":"query","required":false,"schema":{"description":"Number of organizations to retrieve per page.","type":"integer","example":null}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"isPublished","in":"query","description":"Filter by publish state: `true` for published locations, `false` for drafts. Omit for both.","required":false,"schema":{"type":"string","enum":["true","false"],"example":"true"}},{"name":"status","in":"query","description":"Filter by status id.","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Organization locations retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"startDate":{"type":"string","format":"date","example":"2026-01-15"},"endDate":{"type":"string","format":"date","example":"2026-01-15"},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"09:00:00"},"convertedStartDate":{"type":"string","format":"date","example":"2026-01-15"},"convertedEndDate":{"type":"string","format":"date","example":"2026-01-15"},"convertedStartTime":{"type":"string","format":"time","example":"09:00:00"},"convertedEndTime":{"type":"string","format":"time","example":"09:00:00"},"userTimezone":{"type":"string","example":"America/New_York"},"timezone":{"type":"string","example":"America/New_York"},"assignmentDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"userDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"requestedOn":{"type":"string","example":"string"},"submissionDate":{"type":"string","format":"date","example":"2026-01-15"},"timeSlots":{"properties":{"id":{"type":"integer","example":1},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"09:00:00"}},"type":"object"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"startDate":"2026-01-15","endDate":"2026-01-15","startTime":"09:00:00","endTime":"09:00:00","convertedStartDate":"2026-01-15","convertedEndDate":"2026-01-15","convertedStartTime":"09:00:00","convertedEndTime":"09:00:00","userTimezone":"America/New_York","timezone":"America/New_York","assignmentDateTooltip":"Jan 15, 2026 9:00 AM – 11:00 AM","userDateTooltip":"Jan 15, 2026 9:00 AM – 11:00 AM","requestedOn":"string","submissionDate":"2026-01-15","timeSlots":{"id":1,"startTime":"09:00:00","endTime":"09:00:00"}}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":1}}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:read","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/organization-locations/export":{"get":{"tags":["Settings · Organization Locations"],"summary":"Export organization Locations to Excel","description":"**Required scope:** `settings_locations:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all organization Locations to an Excel file for download.","operationId":"ext_get_organization_locations_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"query","description":"Optional organization Location ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing all organization Locations","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:read","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/organization/active-locations":{"get":{"tags":["Settings · Organization Locations"],"summary":"Retrieve active and published locations for a specific organization","description":"**Required scope:** `settings_locations:read`  \n**Roles:** admin, scheduler\n\nFetches only the locations that are both active (status) and published for the current portal organization (based on `portalOrganizationId`), returning minimal details such as label, address, and primary flag.","operationId":"ext_get_organization_active_locations","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Active and published organization location details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Active published Organization Location details retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLTLOC-HQBS7"},"label":{"type":"string","example":"Example label"},"addressLine1":{"type":"string","example":"123 Main St"},"addressLine2":{"type":"string","example":"Suite 200"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"code":{"type":"string","example":"string"}},"type":"object"},"postalCode":{"type":"string","example":"90210"},"isPrimary":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Active published Organization Location details retrieved!","data":[{"id":"CLTLOC-HQBS7","label":"Example label","addressLine1":"123 Main St","addressLine2":"Suite 200","city":"Austin","state":{"id":1,"label":"Example label","code":"string"},"postalCode":"90210","isPrimary":true,"isDefault":true}]}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid Organization ID","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Organization ID is required."},"errors":{"type":"string","nullable":true}},"type":"object"},"example":{"success":false,"message":"Organization ID is required.","errors":null}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred — please try again."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:read","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/organization/locations":{"get":{"tags":["Settings · Organization Locations"],"summary":"Retrieve all locations for a specific organization","description":"**Required scope:** `settings_locations:read`  \n**Roles:** admin, scheduler\n\nFetches all locations associated with the current portal organization (based on `portalOrganizationId`), returning minimal details such as label, address, and primary flag.","operationId":"ext_get_organization_locations_2","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Organization location details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Organization Location details retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLTLOC-HQBS7"},"label":{"type":"string","example":"Example label"},"addressLine1":{"type":"string","example":"123 Main St"},"addressLine2":{"type":"string","example":"Suite 200"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"code":{"type":"string","example":"string"}},"type":"object"},"postalCode":{"type":"string","example":"90210"},"isPrimary":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Organization Location details retrieved!","data":[{"id":"CLTLOC-HQBS7","label":"Example label","addressLine1":"123 Main St","addressLine2":"Suite 200","city":"Austin","state":{"id":1,"label":"Example label","code":"string"},"postalCode":"90210","isPrimary":true,"isDefault":true}]}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid Organization ID","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Organization ID is required."},"errors":{"type":"string","nullable":true}},"type":"object"},"example":{"success":false,"message":"Organization ID is required.","errors":null}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred — please try again."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:read","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/portal/client/assignment":{"get":{"tags":["Assignments"],"summary":"Retrieve paginated client assignments with optional filters","description":"**Required scope:** `assignments:read`  \n**Roles:** client\n\nFetch a paginated list of client assignments. Supports searching, filtering, and sorting.","operationId":"ext_get_portal_client_assignment","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search keyword","schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated list of searchable columns","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Column to sort by","schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Items per page","schema":{"type":"integer","example":10}},{"name":"locationType","in":"query","description":"Filter by location type","schema":{"type":"string","enum":["Onsite","Remote","Hybrid"]}},{"name":"serviceTypes","in":"query","description":"Filter by service type IDs","schema":{"type":"array","items":{"type":"integer"}}},{"name":"consumer","in":"query","description":"Filter by consumer ID. Must be a consumer associated with the authenticated client — otherwise the request is rejected with a 400.","required":false,"schema":{"type":"string","example":"CSM-YWUOOH"}},{"name":"status","in":"query","description":"Filter by assignment-status ID. Statuses are tenant-configurable rows, not a fixed vocabulary.","required":false,"schema":{"type":"integer","example":1}},{"name":"customTab","in":"query","description":"Preset filter tab, applied in addition to any other filters.","required":false,"schema":{"type":"string","enum":["active","archived","upcoming"],"example":"active"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-09-12"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-09-12"}},{"name":"startTime","in":"query","description":"Filter assignments whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime; an overnight range (startTime later than endTime) is handled as spanning midnight.","required":false,"schema":{"type":"string","format":"time","example":"09:00:00"}},{"name":"endTime","in":"query","description":"Filter assignments whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","required":false,"schema":{"type":"string","format":"time","example":"17:00:00"}},{"name":"priority","in":"query","description":"Filter by priority id.","required":false,"schema":{"type":"integer","example":2}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"requestSource","in":"query","description":"Filter by the Request Source column (origin of the request).","required":false,"schema":{"type":"string","enum":["client-portal","consumer-portal","scheduler","public-assistant"],"example":"client-portal"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-XY9EML"},"title":{"type":"string","example":"Example title","nullable":true},"parentTitle":{"type":"string","example":"Example title","nullable":true},"parentId":{"type":"string","nullable":true},"parentScheduleTypeLabel":{"type":"string","example":"Example label","nullable":true},"isParent":{"type":"boolean","example":true},"childCount":{"type":"string","nullable":true},"scheduleTypeLabel":{"type":"string","example":"Example label","nullable":true},"scheduleType":{"type":"string","example":"one_time","nullable":true},"duration":{"type":"number","example":0,"nullable":true},"status":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object","nullable":true},"priority":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object","nullable":true},"broadcast":{"properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object","nullable":true},"providers":{"type":"array","items":[]},"serviceProviders":{"type":"array","items":[],"nullable":true},"groupedProvider":{"type":"array","items":[],"nullable":true},"locationType":{"type":"string","nullable":true},"address":{"properties":{"locationType":{"type":"string"}},"type":"object","nullable":true},"serviceTypes":{"type":"string","nullable":true},"estimatedCost":{"type":"string"},"finalCost":{"type":"string"},"update":{"type":"string"},"consumers":{"type":"array","items":[],"nullable":true},"groupedConsumer":{"type":"string","nullable":true},"createdBy":{"type":"string","nullable":true},"requestorName":{"type":"string","example":"Example name","nullable":true},"requestedVia":{"type":"string","nullable":true},"restrictedActionButtons":{"type":"string"},"clients":{"type":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request — also returned when `consumer` is not associated with the authenticated client","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have access to this consumer. Please select one from your consumer list."},"errors":{"type":"string","example":"Failed to retrieve."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["client"],"x-fido-area":"Client portal","x-fido-area-rank":6}},"/v1/portal/client/assignment/finance/expense-share":{"post":{"tags":["Finances"],"summary":"Approve/decline client expense share per expense line","description":"**Required scope:** `finance:write`  \n**Roles:** client\n\nClient approves or declines their allocated share for one or more client-billable expense lines on an assignment or shift using unified expenses[]. decline_reason is required when action=decline. Decline is final per expense line, and an approved line cannot be approved again. One distinct expense line returns the single-line object in data; two or more return data.results[] and data.errors[] with message 'Expense share bulk action completed.' — a line that fails in a bulk request lands in errors[] and does not fail the request.","operationId":"ext_post_portal_client_assignment_finance_expense_share","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["action","expenses","id"],"properties":{"id":{"description":"Work item id (ASG-* assignment id or SFT-* shift id). The authenticated client must be linked to it.","type":"string","pattern":"^(ASG|SFT)-","example":"SFT-TJRKRR"},"type":{"description":"Optional. Ignored if provided; server derives type from id prefix.","type":"string","enum":["assignment","shift"],"example":"shift","nullable":true},"action":{"description":"Action to perform","type":"string","enum":["approve","decline"],"example":"approve"},"expenses":{"description":"Unified payload for single and bulk actions. Duplicate lines are collapsed; a row whose id is not a positive integer is skipped.","type":"array","items":{"required":["isDefault","id"],"properties":{"isDefault":{"description":"true = expense line from the catalog template, false = custom expense line.","type":"boolean","example":true},"id":{"description":"Expense line id: the template line id when isDefault=true, the custom expense id when isDefault=false.","type":"integer","minimum":1,"example":253},"service_provider_id":{"description":"Owning provider for a template line (isDefault=true). Required when multiple providers are on the work item; auto-inferred when only one provider is assigned. Read only from template rows, and the first non-empty value applies to every template line in the request — send one provider's lines per request. Ignored on custom rows.","type":"string","example":"SPR-ABC123","nullable":true}},"type":"object"},"minItems":1},"service_provider_id":{"description":"Not read. The provider is taken from expenses[].service_provider_id; a top-level value is accepted and ignored.","type":"string","example":"SPR-ABC123","nullable":true},"decline_reason":{"description":"Required when action=decline","type":"string","maxLength":2000,"example":"Not approved","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Expense share action completed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"description":"'Expense share action completed successfully.' for a single line; 'Expense share bulk action completed.' for bulk","type":"string","example":"Expense share action completed successfully."},"data":{"type":"object","oneOf":[{"description":"Single expense line response","properties":{"isDefault":{"description":"Echoed when using expenses[] payload","type":"boolean","example":true},"id":{"description":"Echoed when using expenses[] payload","type":"integer","example":253},"work_item_reimbursable_expense_id":{"description":"Template expense line id; null when custom_expense_id is used.","type":"integer","example":253,"nullable":true},"custom_expense_id":{"description":"Custom expense line id; absent for a template line","type":"integer","example":991,"nullable":true},"service_provider_id":{"description":"Provider the line belongs to; present only when the approval row is provider-scoped (template lines)","type":"string","example":"SPR-ABC123"},"status":{"type":"string","enum":["pending","approved","declined"],"example":"approved"},"approved_at":{"type":"string","example":"2026-03-02T10:00:00+00:00","nullable":true},"approved_by":{"properties":{"id":{"type":"string","example":"CLT-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"approved_share_total":{"type":"number","format":"float","example":10.5,"nullable":true},"declined_at":{"type":"string","example":null,"nullable":true},"declined_by":{"properties":{"id":{"type":"string","example":"CLT-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"decline_reason":{"type":"string","example":null,"nullable":true}},"type":"object"},{"description":"Bulk response","properties":{"results":{"type":"array","items":{"properties":{"isDefault":{"type":"boolean","example":true},"id":{"type":"integer","example":253},"work_item_reimbursable_expense_id":{"type":"integer","example":253,"nullable":true},"custom_expense_id":{"description":"Absent for a template line","type":"integer","example":991,"nullable":true},"service_provider_id":{"description":"Present only when the approval row is provider-scoped (template lines)","type":"string","example":"SPR-ABC123"},"status":{"type":"string","enum":["pending","approved","declined"],"example":"approved"},"approved_at":{"type":"string","example":"2026-03-02T10:00:00+00:00","nullable":true},"approved_by":{"properties":{"id":{"type":"string","example":"CLT-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"approved_share_total":{"type":"number","format":"float","example":10.5,"nullable":true},"declined_at":{"type":"string","example":null,"nullable":true},"declined_by":{"properties":{"id":{"type":"string","example":"CLT-ABC123"},"name":{"type":"string","example":"John Doe"}},"type":"object","nullable":true},"decline_reason":{"type":"string","example":null,"nullable":true}},"type":"object"}},"errors":{"description":"Lines that were not actioned. Each carries either reimbursable_expense_id (template line) or custom_expense_id (custom line), never both.","type":"array","items":{"properties":{"isDefault":{"type":"boolean","example":false},"id":{"type":"integer","example":991},"reimbursable_expense_id":{"description":"Present for a template line","type":"integer","example":253},"custom_expense_id":{"description":"Present for a custom line","type":"integer","example":991},"message":{"type":"string","example":"Expense not in client's share."}},"type":"object"}}},"type":"object"}]}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The authenticated client is not linked to the work item","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'finance:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error — a request field failed validation; a template line names no service_provider_id while several providers are on the work item, or no provider is assigned yet (single and bulk); or, for a single line, it is not in the client's share, canceled or changes_required, missing its receipt, already approved, or already declined","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"service_provider_id is required when multiple providers are on this work item."},"errors":{"type":"object","example":{"service_provider_id":["service_provider_id is required when multiple providers are on this work item."]},"additionalProperties":{"type":"array","items":{"type":"string"}}},"code":{"type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"finance:write","x-fido-module":"finance","x-fido-roles":["client"],"x-fido-area":"Provider expenses","x-fido-area-rank":4}},"/v1/portal/client/assignment/{tab}/{id}":{"get":{"tags":["Assignments"],"summary":"Retrieve specific tab details of client assignment","description":"**Required scope:** `assignments:read`  \n**Roles:** client\n\nFetches the details for a specific tab within an assignment, based on the provided assignment ID and tab identifier. The response structure varies depending on the tab parameter. Supported tabs: 'details', 'providers', 'requirement_and_preferences', 'document_notes', 'sidebar', 'provider_stats', 'summary', 'historyLogs', 'finance'.","operationId":"ext_get_portal_client_assignment_By_tab_By_id","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details','providers','requirement_and_preferences','document_notes','sidebar','provider_stats','summary','historyLogs','finance')","required":true,"schema":{"type":"string","enum":["details","providers","requirement_and_preferences","document_notes","sidebar","provider_stats","summary","historyLogs","finance"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search the audit log. Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated columns the search is limited to. Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort column (default: created_at). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort direction (default: desc). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Rows per page (default: 10). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number (default: 1). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Assignment details retrieved successfully. Note: Response structure varies by tab parameter. The properties below show examples for 'details' tab. For 'finance' tab, see the finance-specific properties documented below.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment details retrieved successfully."},"data":{"description":"Response structure varies by tab. Properties below are for 'details' tab. For 'finance' and 'summary' tabs, see billingSummary and lineItems (same invoice-style billing data on both). Finance tab also includes chargesSummary and assignmentDurationAndCost.","properties":{"id":{"type":"string","example":"ASG-J5A17Q-C2"},"title":{"type":"string","example":"Assignment"},"description":{"type":"string","example":"Manage assignment details, including clients, providers, service locations, and access instructions"},"requestorName":{"type":"string","example":"Requestor name"},"requestorEmail":{"type":"string","example":"user@example.com"},"requestorPhone":{"type":"string","example":"9293091253"},"requestorCountryCode":{"type":"string","example":"+1"},"requestorPhoneType":{"type":"string","example":"sms_and_voice"},"requestorPhoneExtension":{"type":"string","example":null,"nullable":true},"assignTo":{"type":"string","example":"client"},"client":{"properties":{"id":{"type":"string","example":"CLT-GGM6R1"},"label":{"type":"string","example":"Client1"}},"type":"object"},"newClient":{"type":"string","example":null,"nullable":true},"newConsumer":{"type":"string","example":null,"nullable":true},"consumer":{"properties":{"id":{"type":"string","example":"CSM-YWUOOH"},"label":{"type":"string","example":"Consumer1"}},"type":"object"},"location":{"properties":{"locationType":{"type":"string","example":"hybrid"},"onsite":{"properties":{"onSiteType":{"type":"string","example":"manual"},"organizationLocationId":{"type":"string","example":null,"nullable":true},"clientLocationId":{"type":"string","example":null,"nullable":true},"manualLocation":{"properties":{"addressLine1":{"type":"string","example":"asas"},"addressLine2":{"type":"string","example":"asas"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Alaska (AK)"}},"type":"object"},"postalCode":{"type":"string","example":"151545"},"accessInstruction":{"type":"string","example":null,"nullable":true}},"type":"object"},"manualLocationContact":{"properties":{"contactName":{"type":"string","example":"asasas"},"contactEmail":{"type":"string","example":"user@example.com"},"contactCountryCode":{"type":"string","example":"+1"},"contactPhone":{"type":"string","example":"454544545"},"contactPhoneType":{"type":"string","example":"sms_and_voice"},"contactPhoneExtension":{"type":"string","example":null,"nullable":true}},"type":"object"},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"serviceProviderType":{"type":"string","example":"Deaf"},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}},"type":"object"},"remote":{"properties":{"meetingPlatform":{"type":"string","example":"Zoom"},"meetingLink":{"type":"string","example":"http://zoom.us/test"},"meetingCountryCode":{"type":"string","example":"+1"},"meetingPhone":{"description":"Dial-in number; replaces meetingLink when meetingPlatform is Phone.","type":"string","example":"2025550147"},"meetingExtension":{"type":"string","example":"204","nullable":true},"accessInstruction":{"type":"string","example":null,"nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"serviceProviderType":{"type":"string","example":"Deaf"},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}},"type":"object"}},"type":"object"},"timezone":{"type":"string","example":null,"nullable":true},"duration":{"type":"integer","example":0},"scheduleType":{"type":"string","example":"one_time"},"childAssignmentIds":{"type":"string","example":null,"nullable":true},"oneTime":{"properties":{"dateTimeSlots":{"type":"array","items":{"properties":{"startDate":{"type":"string","example":"2025-09-06"},"endDate":{"type":"string","example":"2025-09-06"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"13:00:00"},"endTime":{"type":"string","example":"16:00:00"}},"type":"object"}}},"type":"object"}}},"type":"object"},"multiDay":{"properties":{"dateTimeSlots":{"type":"array","items":{"type":"object"}}},"type":"object"},"recurring":{"properties":{"dateTimeSlots":{"type":"array","items":{"type":"object"}}},"type":"object"},"chargesSummary":{"description":"For 'finance' tab: Array of charge summaries","type":"array","items":{"properties":{"rate":{"type":"string","example":"25.00"},"billingServiceRate":{"type":"string","example":"Standard"},"totalBilledAmount":{"type":"string","example":"400.00"},"status":{"type":"string","example":"Pending"}},"type":"object"}},"lineItems":{"description":"For 'finance' tab: Array of invoice line items","type":"array","items":{"properties":{"type":{"properties":{"id":{"type":"string","example":"charge"},"label":{"type":"string","example":"Charge"}},"type":"object"},"item":{"type":"string","example":"Additional Service"},"description":{"type":"string","example":"Extra service charge"},"amount":{"type":"string","example":"100.00"}},"type":"object"}},"billingSummary":{"description":"For 'finance' tab: Billing summary with totals and calculations (subtotal aligns with invoice document subtotal; admin fees from AR work-item charges for this client)","properties":{"taxPercentage":{"type":"number","format":"float","example":5},"discountPercentage":{"type":"number","format":"float","example":5},"subtotal":{"description":"Prorated invoice subtotal (pre-tax gross) for this work item","type":"string","example":"120.00"},"serviceCharges":{"description":"Prorated invoice services_charges for this work item, or estimated service total when no invoice","type":"string","example":"100.00"},"expensesTotal":{"description":"Prorated invoice expenses_total when invoiced; AR expense total when no invoice (client-billed)","type":"string","example":"15.00"},"additionalItems":{"description":"When invoiced: prorated line-charge slice (subtotal minus services, expenses_total, and total_admin_fee). When no invoice: 0","type":"string","example":"5.00"},"organizationAdminFee":{"description":"Organization admin fee from AR charge build for this work item (0 when bill-to organization)","type":"string","example":"5.00"},"providerAdminFee":{"description":"Provider admin fee from AR charge build (0 when bill-to organization)","type":"string","example":"3.00"},"totalAdminFee":{"description":"organizationAdminFee + providerAdminFee from AR charge build","type":"string","example":"8.00"},"credits":{"type":"string","example":"50.00"},"taxAmount":{"type":"string","example":"8.50"},"totalAmount":{"type":"string","example":"228.50"},"invoices":{"description":"Linked invoices for this client and work item (newest issue date first).","type":"array","items":{"properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"link":{"type":"string","example":"https://tenant.example.com/finances/invoices/550e8400-e29b-41d4-a716-446655440000"}},"type":"object"}}},"type":"object"},"assignmentDurationAndCost":{"description":"For 'finance' tab: Assignment duration and cost breakdown","properties":{"estimatedCostBreakdown":{"description":"Breakdown of estimated costs by service type, rate type and site type","type":"array","items":{"properties":{"serviceType":{"type":"string","example":"ASL"},"serviceProviderType":{"description":"Provider type this line is rated for; empty string when the line is not scoped to one.","type":"string","example":"ASL Interpreter"},"rateType":{"type":"string","example":"standard"},"siteType":{"type":"string","example":"onsite"},"hours":{"type":"number","example":8},"rate":{"type":"number","format":"float","example":30},"cost":{"type":"number","format":"float","example":240},"minimum_applied":{"description":"True when the billed duration was floored up to the minimum billing duration.","type":"boolean","example":true},"minimum_duration":{"description":"Minimum billing duration on the same basis as duration; null when no minimum applies to this line.","type":"number","format":"float","example":12,"nullable":true}},"type":"object"}},"totalDuration":{"type":"string","example":"8 hours"},"totalCost":{"type":"string","example":"240.00"}},"type":"object"},"terminalChargeMode":{"description":"Present only when work item is canceled or no-show, client is not org-billed, and no posted invoice exists for this client. Indicates which terminal billing rules applied.","type":"string","enum":["canceled","no_show"],"example":"canceled"},"chargeSource":{"description":"AR charge source for this client (e.g. cancellation_fee, no_show_client_split, service_charge). Present with terminalChargeMode.","type":"string","example":"cancellation_fee"},"billableServiceCharges":{"description":"Billable service amount for this client under terminal rules. Present with terminalChargeMode.","type":"string","example":"75.00"},"billableSubtotal":{"description":"Pre-tax gross: billableServiceCharges + approved client expenses + admin fees. Present with terminalChargeMode.","type":"string","example":"95.00"},"cancellationFee":{"description":"This client's cancellation fee total when terminalChargeMode is canceled; otherwise omitted or null.","type":"string","example":"75.00","nullable":true},"noShowFee":{"description":"Stored no-show fee for this client when terminalChargeMode is no_show and client is selected; otherwise omitted or null.","type":"string","example":"50.00","nullable":true},"expenses":{"description":"Reimbursable expenses for the assignment (same format as work item expenses)","properties":{"items":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Mileage"},"rate":{"type":"number","format":"float","example":0.67},"unit":{"type":"string","example":"mile"}},"type":"object"}},"total":{"type":"number","format":"float","example":0}},"type":"object"},"expenseBreakdownByProvider":{"description":"Per-provider client expense breakdown (additive). Use this for approve/decline actions when multiple providers are on the work item. Legacy expenseBreakdown remains aggregated.","properties":{"providers":{"type":"array","items":{"properties":{"service_provider_id":{"type":"string","example":"USR-ABC123"},"providerName":{"type":"string","example":"Jane Provider"},"image":{"type":"string","example":"https://example.com/provider-logo.jpg","nullable":true},"total":{"type":"string","example":"25.00"},"approved_total":{"type":"string","example":"10.00"},"expenseApproveEnabled":{"description":"True when the client can approve at least one expense in this provider's block under the current expense approval workflow.","type":"boolean","example":true},"items":{"type":"array","items":{"properties":{"id":{"type":"integer","example":253},"service_provider_id":{"type":"string","example":"USR-ABC123"},"providerName":{"type":"string","example":"Jane Provider"},"status":{"type":"string","enum":["pending","approved","declined"],"example":"pending"},"actions":{"properties":{"canApprove":{"type":"boolean","example":true},"canDecline":{"type":"boolean","example":true}},"type":"object","nullable":true}},"type":"object"}}},"type":"object"}},"total":{"type":"string","example":"25.00"},"approved_total":{"type":"string","example":"10.00"}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified assignment does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified assignment does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["client"],"x-fido-area":"Client portal","x-fido-area-rank":6}},"/v1/portal/client/request-form":{"get":{"tags":["Forms"],"summary":"Fetch the custom form for the client portal Add Request screen","description":"**Required scope:** `forms:read`  \n**Roles:** client\n\nSame body as GET /forms/module-fields/client_request, for a client portal user (who has no Forms access). Always the module's generic active form, the one the create and update requests validate against; assignTo, clientId and locationId query values are ignored.","operationId":"ext_get_portal_client_request_form","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Array of form schemas, or null when no active form applies","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Form fields retrieved!"},"data":{"description":"One entry per active form in scope, each in the same shape the form-details endpoint returns, with each field's empty value filled in, archived placements dropped and a usage count attached. Sent as null — not an empty array — when no active form applies.","type":"array","items":{"properties":{"form":{"properties":{"id":{"description":"The form code.","type":"string","example":"FRM-7KQ2PA"},"name":{"type":"string","example":"Intake"},"description":{"type":"string","nullable":true},"isPublished":{"type":"boolean","example":true},"formType":{"type":"string","example":"internal","nullable":true},"moduleType":{"properties":{"id":{"type":"string","example":"client"},"label":{"type":"string","example":"Client"}},"type":"object","nullable":true},"status":{"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Active"}},"type":"object","nullable":true},"assignTo":{"properties":{"id":{"type":"string","example":"organization"},"label":{"type":"string","example":"Organization"},"isCustom":{"type":"boolean","example":false}},"type":"object","nullable":true},"version":{"type":"integer","example":2,"nullable":true},"multiStep":{"type":"boolean","example":false},"reviewStep":{"description":"Only meaningful while multiStep is true.","type":"boolean","example":false},"externalVisibility":{"properties":{"id":{"type":"string","enum":["public","private"],"example":"private"},"label":{"type":"string","example":"Private"}},"type":"object","nullable":true},"lastUsedDate":{"type":"string","example":"01/15/2025","nullable":true},"settings":{"type":"object","nullable":true}},"type":"object"},"startsStep":{"type":"integer","example":1,"nullable":true},"groups":{"description":"Field groups in render order; a single-step form has one.","type":"array","items":{"properties":{"label":{"type":"string","example":"Contact","nullable":true},"isRequired":{"type":"boolean","example":false},"isArchived":{"type":"boolean","example":false},"fields":{"type":"array","items":{"properties":{"fieldKey":{"type":"string","example":"preferred_name"},"label":{"type":"string","example":"Preferred name"},"type":{"type":"string","example":"text"},"isDefault":{"type":"boolean","example":false},"isRequired":{"type":"boolean","example":true},"isArchived":{"type":"boolean","example":false},"value":{"description":"The field's type-correct empty value in add mode: false, null, [] or the empty string.","nullable":true},"usageCount":{"description":"Active forms this field appears on.","type":"integer","example":3,"nullable":true},"settings":{"type":"object","nullable":true},"ui":{"properties":{"placeholder":{"type":"string","nullable":true},"style":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"cssClass":{"type":"string","nullable":true},"checkboxType":{"type":"string","nullable":true}},"type":"object","nullable":true},"validation":{"properties":{"required":{"type":"boolean","example":true}},"type":"object","nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"},"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:read","x-fido-module":"forms","x-fido-roles":["client"],"x-fido-area":"Request forms in the portals","x-fido-area-rank":1}},"/v1/portal/consumer/assignment":{"get":{"tags":["Assignments"],"summary":"Retrieve paginated consumer assignments with optional filters","description":"**Required scope:** `assignments:read`  \n**Roles:** consumer\n\nFetch a paginated list of consumer assignments. Supports searching, filtering, and sorting.","operationId":"ext_get_portal_consumer_assignment","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search keyword","schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated list of searchable columns","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Column to sort by","schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Items per page","schema":{"type":"integer","example":10}},{"name":"locationType","in":"query","description":"Filter by location type","schema":{"type":"string","enum":["Onsite","Remote","Hybrid"]}},{"name":"serviceTypes","in":"query","description":"Filter by service type IDs","schema":{"type":"array","items":{"type":"integer"}}},{"name":"client","in":"query","description":"Filter by client","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by assignment status","schema":{"type":"string","enum":["Pending","Approved","Rejected","Assigned","No Show"]}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-09-12"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-09-12"}},{"name":"requestSource","in":"query","description":"Filter by the Request Source column (origin of the request).","required":false,"schema":{"type":"string","enum":["client-portal","consumer-portal","scheduler","public-assistant"],"example":"client-portal"}},{"name":"startTime","in":"query","description":"Filter assignments whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime; an overnight range (startTime later than endTime) is handled as spanning midnight.","required":false,"schema":{"type":"string","format":"time","example":"09:00:00"}},{"name":"endTime","in":"query","description":"Filter assignments whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","required":false,"schema":{"type":"string","format":"time","example":"17:00:00"}},{"name":"priority","in":"query","description":"Filter by priority id.","required":false,"schema":{"type":"integer","example":2}},{"name":"customTab","in":"query","description":"Preset filter tab, applied in addition to any other filters.","required":false,"schema":{"type":"string","enum":["active","archived","past","upcoming","need_attention"],"example":"active"}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-J5A17Q"},"title":{"type":"string","example":"Assignment"},"isParent":{"type":"boolean","example":true},"scheduleTypeLabel":{"type":"string","example":"Multi Day"},"scheduleType":{"type":"string","example":"multi_day"},"startDate":{"type":"string","example":"9/05/2025"},"endDate":{"type":"string","example":"9/06/2025"},"startTime":{"type":"string","example":"11:00 AM"},"endTime":{"type":"string","example":"5:00 PM"},"timezone":{"type":"string","example":null,"nullable":true},"broadcast":{"type":"string","example":null,"nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Pending"}},"type":"object"},"serviceProviders":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-MD5MK3"},"image":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg"}},"type":"object"}},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"locationType":{"type":"string","example":"Hybrid"},"address":{"properties":{"onsite":{"properties":{"title":{"type":"string","example":null,"nullable":true},"onSiteType":{"type":"string","example":"manual"},"address":{"properties":{"addressLine1":{"type":"string","example":"asas"},"addressLine2":{"type":"string","example":"asas"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Alaska (AK)"}},"type":"object"},"postalCode":{"type":"string","example":"151545"}},"type":"object"}},"type":"object"},"remote":{"properties":{"remoteAccessDetails":{"properties":{"url":{"type":"string","example":"http://zoom.us/test"},"notes":{"type":"string","example":null,"nullable":true},"meetingPlatform":{"type":"string","example":"Zoom"}},"type":"object"}},"type":"object"}},"type":"object"},"update":{"type":"string","example":"Provider assigned","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":3}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request — also returned when `client` is not associated with the authenticated consumer","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have access to this client. Please select one from your client list."},"errors":{"type":"string","example":"Failed to retrieve."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":7}},"/v1/portal/consumer/assignment/{tab}/{id}":{"get":{"tags":["Assignments"],"summary":"Retrieve specific tab details of consumer assignment","description":"**Required scope:** `assignments:read`  \n**Roles:** consumer\n\nFetches the details for a specific tab within an assignment, based on the provided assignment ID and tab identifier.","operationId":"ext_get_portal_consumer_assignment_By_tab_By_id","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment","required":true,"schema":{"type":"string","example":"ASG-J5A17Q-C1"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details','providers','requirement_and_preferences','document_notes','sidebar')","required":true,"schema":{"type":"string","enum":["details","providers","requirement_and_preferences","document_notes","sidebar"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Assignment details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment details retrieved successfully."},"data":{"properties":{"assignmentDetails":{"properties":{"id":{"type":"string","example":"ASG-J5A17Q-C1"},"title":{"type":"string","example":"Assignment"},"description":{"type":"string","example":"Manage assignment details, including clients, providers, service locations, and access instructions"},"timezone":{"type":"string","example":null,"nullable":true},"duration":{"type":"integer","example":0},"status":{"properties":{"id":{"type":"integer","example":5},"label":{"type":"string","example":"Scheduled"}},"type":"object"},"scheduleTypeLabel":{"type":"string","example":"one_time"},"locationType":{"type":"string","example":"hybrid"},"startDate":{"type":"string","example":"9/05/2025"},"endDate":{"type":"string","example":"9/05/2025"},"startTime":{"type":"string","example":"11:00 AM"},"endTime":{"type":"string","example":"5:00 PM"}},"type":"object"},"onSiteContact":{"properties":{"title":{"type":"string","example":"On-Site Contact"},"name":{"type":"string","example":"asasas"},"email":{"type":"string","example":"user@example.com"},"phone":{"type":"string","example":"454544545"},"countryCode":{"type":"string","example":"+1"},"phoneType":{"type":"string","example":"sms_and_voice"},"phoneExtension":{"type":"string","example":null,"nullable":true},"logo":{"type":"string","example":null,"nullable":true}},"type":"object"},"assignmentLocation":{"properties":{"locationType":{"type":"string","example":"hybrid"},"onsite":{"properties":{"locationType":{"type":"string","example":"On-Site"},"title":{"type":"string","example":null,"nullable":true},"onSiteType":{"type":"string","example":"manual"},"address":{"properties":{"addressLine1":{"type":"string","example":"asas"},"addressLine2":{"type":"string","example":"asas"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Alaska (AK)"}},"type":"object"},"postalCode":{"type":"string","example":"151545"},"accessInstruction":{"type":"string","example":null,"nullable":true}},"type":"object"},"location_note":{"type":"string","example":null,"nullable":true},"serviceProviders":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"serviceType":{"type":"string","example":"ASL"},"assignedProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"},"remote":{"properties":{"locationType":{"type":"string","example":"Remote"},"remoteAccessDetails":{"properties":{"meetingPlatform":{"type":"string","example":"Zoom"},"url":{"type":"string","example":"http://zoom.us/test"},"notes":{"type":"string","example":null,"nullable":true}},"type":"object"},"serviceProviders":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"serviceType":{"type":"string","example":"ASL"},"assignedProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}},"type":"object"},"childAssignmentIds":{"type":"string","example":null,"nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified assignment does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified assignment does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":7}},"/v1/portal/consumer/request-form":{"get":{"tags":["Forms"],"summary":"Fetch the custom form for the consumer portal Add Request screen","description":"**Required scope:** `forms:read`  \n**Roles:** consumer\n\nSame as the client portal route, for the consumer_request module.","operationId":"ext_get_portal_consumer_request_form","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Array of form schemas, or null when no active form applies","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Form fields retrieved!"},"data":{"description":"One entry per active form in scope, each in the same shape the form-details endpoint returns, with each field's empty value filled in, archived placements dropped and a usage count attached. Sent as null — not an empty array — when no active form applies.","type":"array","items":{"properties":{"form":{"properties":{"id":{"description":"The form code.","type":"string","example":"FRM-7KQ2PA"},"name":{"type":"string","example":"Intake"},"description":{"type":"string","nullable":true},"isPublished":{"type":"boolean","example":true},"formType":{"type":"string","example":"internal","nullable":true},"moduleType":{"properties":{"id":{"type":"string","example":"client"},"label":{"type":"string","example":"Client"}},"type":"object","nullable":true},"status":{"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Active"}},"type":"object","nullable":true},"assignTo":{"properties":{"id":{"type":"string","example":"organization"},"label":{"type":"string","example":"Organization"},"isCustom":{"type":"boolean","example":false}},"type":"object","nullable":true},"version":{"type":"integer","example":2,"nullable":true},"multiStep":{"type":"boolean","example":false},"reviewStep":{"description":"Only meaningful while multiStep is true.","type":"boolean","example":false},"externalVisibility":{"properties":{"id":{"type":"string","enum":["public","private"],"example":"private"},"label":{"type":"string","example":"Private"}},"type":"object","nullable":true},"lastUsedDate":{"type":"string","example":"01/15/2025","nullable":true},"settings":{"type":"object","nullable":true}},"type":"object"},"startsStep":{"type":"integer","example":1,"nullable":true},"groups":{"description":"Field groups in render order; a single-step form has one.","type":"array","items":{"properties":{"label":{"type":"string","example":"Contact","nullable":true},"isRequired":{"type":"boolean","example":false},"isArchived":{"type":"boolean","example":false},"fields":{"type":"array","items":{"properties":{"fieldKey":{"type":"string","example":"preferred_name"},"label":{"type":"string","example":"Preferred name"},"type":{"type":"string","example":"text"},"isDefault":{"type":"boolean","example":false},"isRequired":{"type":"boolean","example":true},"isArchived":{"type":"boolean","example":false},"value":{"description":"The field's type-correct empty value in add mode: false, null, [] or the empty string.","nullable":true},"usageCount":{"description":"Active forms this field appears on.","type":"integer","example":3,"nullable":true},"settings":{"type":"object","nullable":true},"ui":{"properties":{"placeholder":{"type":"string","nullable":true},"style":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"cssClass":{"type":"string","nullable":true},"checkboxType":{"type":"string","nullable":true}},"type":"object","nullable":true},"validation":{"properties":{"required":{"type":"boolean","example":true}},"type":"object","nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"},"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"forms:read","x-fido-module":"forms","x-fido-roles":["consumer"],"x-fido-area":"Request forms in the portals","x-fido-area-rank":1}},"/v1/portal/provider/requests":{"get":{"tags":["Requests"],"summary":"Retrieve paginated provider requests with optional filters","description":"**Required scope:** `requests:read`  \n**Roles:** service-provider\n\nFetch a paginated list of provider request assignments. Allows filtering, searching, and sorting. Each item adds myTime and myConvertedTime: the provider's own covered hours on that occurrence when they hold only part of a partial-coverage job ('12:00 PM to 4:00 PM', separate runs joined with ', '), null otherwise. startTime/endTime keep the whole job's range.","operationId":"ext_get_portal_provider_requests","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search keyword","schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated list of searchable columns","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Column to sort by","schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Items per page","schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number to retrieve","schema":{"type":"integer","example":1}},{"name":"locationType","in":"query","description":"Filter by location type","schema":{"type":"string","enum":["Onsite","Remote","Hybrid"]}},{"name":"duration","in":"query","description":"Filter by duration","schema":{"type":"integer"}},{"name":"distance","in":"query","description":"Filter by distance (e.g., '5 miles')","schema":{"type":"string"}},{"name":"serviceTypes","in":"query","description":"Filter by service type IDs","schema":{"type":"array","items":{"type":"integer"}}},{"name":"client","in":"query","description":"Filter by client","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by assignment status","schema":{"type":"string","enum":["Pending","Approved","Rejected","Assigned"]}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-09-12"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-09-12"}},{"name":"clientType","in":"query","description":"Filter by the Client Type column. Hyphenated spellings (single-location) match too.","required":false,"schema":{"type":"string","enum":["individual","single_location","multi_location"],"example":"single_location"}},{"name":"partialCover","in":"query","description":"Filter by the Partial Cover column: true for work items that allow partial coverage, false for those that do not.","required":false,"schema":{"type":"boolean","example":true}},{"name":"requestSource","in":"query","description":"Filter by the Request Source column (origin of the request).","required":false,"schema":{"type":"string","enum":["client-portal","consumer-portal","scheduler","public-assistant"],"example":"client-portal"}},{"name":"startTime","in":"query","description":"Filter requests whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime; an overnight range (startTime later than endTime) is handled as spanning midnight.","required":false,"schema":{"type":"string","format":"time","example":"09:00:00"}},{"name":"endTime","in":"query","description":"Filter requests whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","required":false,"schema":{"type":"string","format":"time","example":"17:00:00"}},{"name":"localSearch","in":"query","description":"The table's own search box: matches only the columns named in `columns`. `search` is the global search.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-DYKTKO"},"assignmentName":{"type":"string","example":"Assignment 4"},"clientType":{"type":"string","example":null,"nullable":true},"providers":{"type":"array","items":{"type":"string"},"example":["2 Deaf","2 Hearing"]},"startDate":{"type":"string","example":"9/12/2025"},"endDate":{"type":"string","example":"9/12/2025"},"startTime":{"type":"string","example":"12:00 PM"},"endTime":{"type":"string","example":"1:00 PM"},"duration":{"type":"integer","example":null,"nullable":true},"locationType":{"type":"string","example":"Hybrid"},"address":{"properties":{"onsite":{"properties":{"title":{"type":"string","example":null,"nullable":true},"onSiteType":{"type":"string","example":"manual"},"address":{"properties":{"addressLine1":{"type":"string","example":"asas"},"addressLine2":{"type":"string","example":"asas"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Alaska (AK)"}},"type":"object"},"postalCode":{"type":"string","example":"151545"}},"type":"object"}},"type":"object"},"remote":{"properties":{"remoteAccessDetails":{"properties":{"url":{"type":"string","example":"http://zoom.us/test"},"notes":{"type":"string","example":null,"nullable":true},"meetingPlatform":{"type":"string","example":"Zoom"}},"type":"object"}},"type":"object"}},"type":"object"},"distance":{"type":"string","example":"5.2 miles"},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"partialCoverage":{"type":"boolean","example":false},"estimatePay":{"type":"number","example":0},"scheduleType":{"type":"string","example":"one_time"},"update":{"type":"string","example":null,"nullable":true},"status":{"type":"string","example":"Pending"},"notesFromScheduler":{"type":"string","example":null,"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":4}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"object","example":{"search":["Invalid search parameter"]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":2},"post":{"tags":["Requests"],"summary":"Accept assignment slots for a request","description":"**Required scope:** `requests:write`  \n**Roles:** service-provider\n\nAssigns the provider to selected slots of an assignment and returns the status with accepted slots.","operationId":"ext_post_portal_provider_requests","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["requestAssignment"],"properties":{"acknowledge_conflicts":{"description":"Send true after the provider has confirmed a schedule conflict (409 provider_conflict_confirmation_required). Also accepted inside requestAssignment, as 1/true.","type":"boolean","example":false},"requestAssignment":{"required":["assignmentId"],"properties":{"assignmentId":{"type":"string","example":"ASG-JSPYP1"},"acceptSlots":{"type":"array","items":{"required":["id","locationTypeId","slotId","status"],"properties":{"id":{"type":"integer","example":107},"locationTypeId":{"type":"integer","example":112},"slotId":{"type":"integer","example":92},"status":{"type":"string","example":"assigned"}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"responses":{"200":{"description":"Assigned assignment successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assigned assignment successfully."},"data":{"properties":{"id":{"type":"string","example":"ASG-JSPYP1"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to accept slots."},"errors":{"type":"object","example":{"acceptSlots":["The acceptSlots field is required."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The authenticated provider has no relationship to requestAssignment.assignmentId (never broadcast to, never assigned) — generic message on purpose, so the response can't be used to tell a real id apart from one belonging to someone else.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"409":{"description":"Nothing was written. Either the offer can no longer be accepted (the slot is filled, the offer lapsed or the work was called off), or (code provider_conflict_confirmation_required) the accept clashes with the provider's own work or settings and they have not confirmed. Resend the same request with acknowledge_conflicts true to accept anyway.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Wait, you're already booked for Assignment Clinic visit (ASG-AB12CD) on Mon, May 5, 2031 9:00 AM–10:00 AM CDT, which overlaps this assignment on Mon, May 5, 2031 9:30 AM–10:30 AM CDT. Accept anyway?"},"code":{"type":"string","example":"provider_conflict_confirmation_required"},"errors":{"description":"Present only for provider_conflict_confirmation_required","properties":{"conflicts":{"type":"array","items":{"properties":{"kind":{"type":"string","enum":["overlap","buffer","unavailable","vacation","limit"],"example":"overlap"},"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-AB12CD"},"title":{"type":"string","example":"Clinic visit","nullable":true},"startsAt":{"type":"string","format":"date-time","example":"2031-05-05T14:00:00Z"},"endsAt":{"type":"string","format":"date-time","example":"2031-05-05T15:00:00Z"},"message":{"type":"string"}},"type":"object"}}},"type":"object","nullable":true}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected server error","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":2}},"/v1/portal/provider/requests/assignment-decline/{id}/{status}":{"patch":{"tags":["Requests"],"summary":"Decline a request assignment by ID","description":"**Required scope:** `requests:edit`  \n**Roles:** service-provider\n\nReturns decline assignment ID","operationId":"ext_patch_portal_provider_requests_assignment_decline_By_id_By_status","parameters":[{"name":"id","in":"path","description":"The ID of the assignment entry","required":true,"schema":{"type":"string","example":"ASG-JSPYP1"}},{"name":"status","in":"path","description":"How the provider is turning the request down.","required":true,"schema":{"type":"string","enum":["declined","not_interested"],"example":"declined"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Assignment decline successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment decline successfully."},"data":{"properties":{"id":{"type":"string","example":"ASG-JSPYP1"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment entry not found."},"errors":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:edit","x-fido-module":"requests","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":2}},"/v1/portal/provider/requests/assignment-slot/{id}":{"get":{"tags":["Requests"],"summary":"Retrieve a single request assignment slot by ID","description":"**Required scope:** `requests:read`  \n**Roles:** service-provider\n\nReturns details of assignment time slots including service details, service summary, and addresses.","operationId":"ext_get_portal_provider_requests_assignment_slot_By_id","parameters":[{"name":"id","in":"path","description":"The ID of the assignment entry","required":true,"schema":{"type":"string","example":"ASG-JSPYP1"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Assignment time slot retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment time slot retrieved."},"data":{"type":"array","items":{"properties":{"startDate":{"type":"string","example":"2026-01-15"},"endDate":{"type":"string","example":"2026-01-15"},"slots":{"type":"array","items":{"properties":{"slotId":{"type":"integer","example":97},"startTime":{"type":"string","example":"12:00 PM"},"endTime":{"type":"string","example":"1:00 PM"},"serviceDetails":{"type":"array","items":{"properties":{"id":{"type":"integer","example":117},"assignmentMethod":{"type":"string","example":"accept"},"status":{"type":"string","example":"pending"},"locationtype":{"properties":{"id":{"type":"integer","example":119},"label":{"type":"string","example":"onsite"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"},"totalProvider":{"type":"integer","example":2}},"type":"object"}},"type":"object"}},"serviceTypeSummary":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"serviceTypeName":{"type":"string","example":"ASL"},"required":{"type":"integer","example":2},"assigned":{"type":"integer","example":0},"status":{"type":"string","example":"not filled"}},"type":"object"}},"address":{"properties":{"onsite":{"properties":{"title":{"type":"string","example":null,"nullable":true},"onSiteType":{"type":"string","example":"manual"},"address":{"properties":{"addressLine1":{"type":"string","example":"asas"},"addressLine2":{"type":"string","example":"asas"},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Alaska (AK)"}},"type":"object"},"postalCode":{"type":"string","example":"151545"}},"type":"object"}},"type":"object"},"remote":{"properties":{"remoteAccessDetails":{"properties":{"url":{"type":"string","example":"http://zoom.us/test"},"notes":{"type":"string","example":null,"nullable":true},"meetingPlatform":{"type":"string","example":"Zoom"}},"type":"object"}},"type":"object"}},"type":"object"}},"type":"object"}}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment slot not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment slot not found."},"errors":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":2}},"/v1/portal/provider/requests/remove-alert-dialog/{id}":{"patch":{"tags":["Requests"],"summary":"Remove alert dialog for a request","description":"**Required scope:** `requests:edit`  \n**Roles:** service-provider\n\nMarks the alert dialog as dismissed for the authenticated service provider on a specific assignment or shift request.","operationId":"ext_patch_portal_provider_requests_remove_alert_dialog_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"Unique identifier of the assignment or shift.","required":true,"schema":{"type":"string","example":"ASG-23RT45"}}],"responses":{"200":{"description":"Alert dialog removed successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Alert dialog removed successfully."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to remove alert dialog"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:edit","x-fido-module":"requests","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":2}},"/v1/portal/provider/requests/undo/{id}":{"patch":{"tags":["Requests"],"summary":"Undo declined assignment request","description":"**Required scope:** `requests:edit`  \n**Roles:** service-provider\n\nReverts a previously declined assignment request and restores it to pending state.","operationId":"ext_patch_portal_provider_requests_undo_By_id","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment request","required":true,"schema":{"type":"string","example":"ASG-JSPYP1"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant identifier used for multi-tenant resolution","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Undo decline successful","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"You have successfully undone the decline for this request. The request is now active again"},"data":{"properties":{"id":{"type":"string","example":"ASG-X9C9WG"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment entry not found"},"errors":{"type":"string","example":null,"nullable":true}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected exception details","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:edit","x-fido-module":"requests","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":2}},"/v1/portal/provider/requests/{id}":{"get":{"tags":["Requests"],"summary":"Retrieve a single request assignment entry by ID","description":"**Required scope:** `requests:read`  \n**Roles:** service-provider\n\nReturns details of a specific assignment entry including dates, times, providers, address, services, and status.","operationId":"ext_get_portal_provider_requests_By_id","parameters":[{"name":"id","in":"path","description":"The ID of the assignment entry","required":true,"schema":{"type":"string","example":"ASG-JSPYP1"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Assignment entry retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment list entry retrieved."},"data":{"properties":{"startDate":{"type":"string","example":"9/05/2025"},"endDate":{"type":"string","example":"9/06/2025"},"startTime":{"type":"string","example":"11:00 AM"},"endTime":{"type":"string","example":"5:00 PM"},"id":{"type":"string","example":"ASG-JSPYP1"},"assignmentName":{"type":"string","example":"Assignment 1"},"partialCoverage":{"type":"boolean","example":false},"estimatePay":{"type":"number","example":0},"address":{"properties":{"onsite":{"properties":{"title":{"type":"string","example":"Primary Location"},"onSiteType":{"type":"string","example":"client"},"address":{"properties":{"addressLine1":{"type":"string","example":null,"nullable":true},"addressLine2":{"type":"string","example":null,"nullable":true},"city":{"type":"string","example":null,"nullable":true},"state":{"type":"string","example":null,"nullable":true},"postalCode":{"type":"string","example":null,"nullable":true}},"type":"object"}},"type":"object"}},"type":"object"},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"providers":{"type":"array","items":{"type":"string","example":"1 Deaf"}},"duration":{"type":"string","example":null,"nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Pending"}},"type":"object"},"certification":{"type":"array","items":{"type":"string"},"example":[]}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment entry not found."},"errors":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":2}},"/v1/preference":{"post":{"tags":["Assignments"],"summary":"Resolve client/consumer/org default or override preferences for the assignment/shift form","description":"**Required scope:** `assignments:read` or `shifts:read`\n\nA lookup, not a mutation — despite the POST verb. Three modes: noOverride echoes requirementAndPreferences back unchanged; isDefault resolves the organization → client → consumer default preferences (merging restricted and preferred providers, priority, timezone and, when locationType is sent, default location data); otherwise the clientPreferences, consumerPreferences and serviceProviderPreferences overrides are layered on top of the merged restricted and preferred provider lists. When editing, assignmentId or shiftId also merges in the restrictions of the providers already assigned to that work item.","operationId":"ext_post_preference","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"description":"Every field is optional; the response depends on which combination is sent. Only `client` is validated: it must be an existing client.","properties":{"client":{"description":"A single client id — a bare string, NOT the {id, label} object the assignment/shift create and update endpoints use.","type":"string","example":"CLT-KBX0Q6","nullable":true},"clientIds":{"description":"Comma-separated client ids — the multi-client alternative to client (used for a shift with assignTo=organization and multiple assignClients).","type":"string","example":"CLT-KBX0Q6,CLT-OTHER1","nullable":true},"consumer":{"description":"Comma-separated consumer ids — a plain string, NOT the array-of-objects shape used elsewhere.","type":"string","example":"CSM-SQEWP0T,CSM-OTHER1","nullable":true},"assignTo":{"type":"string","enum":["client","organization"],"example":"client","nullable":true},"isAssignment":{"description":"Selects the assignment vs. shift default-preference column when isDefault is true.","type":"boolean","example":true,"nullable":true},"isDefault":{"description":"Resolves the org→client→consumer default tier instead of applying an override.","type":"boolean","example":true,"nullable":true},"locationType":{"description":"When sent with isDefault, also returns the default location for that type.","type":"string","enum":["onsite","remote","hybrid"],"example":"onsite","nullable":true},"assignmentId":{"description":"When editing an existing assignment, merges in its already-assigned providers' own provider-to-provider restrictions.","type":"string","example":"ASG-SA2IVL","nullable":true},"shiftId":{"description":"Same as assignmentId, for an existing shift.","type":"string","example":"SFT-MNP4PJ","nullable":true},"clientPreferences":{"description":"Override keys the user checked on the client side — e.g. restrictedServiceProvider, preferredServiceProvider.","type":"array","items":{"type":"string","example":"restrictedServiceProvider"},"nullable":true},"consumerPreferences":{"description":"Same override keys, consumer side.","type":"array","items":{"type":"string","example":"restrictedServiceProvider"},"nullable":true},"serviceProviderPreferences":{"description":"Scheduler-side overrides applied to the resulting userRestricted list: restrictedServiceProviders (drop provider-to-provider restrictions), restrictedConsumers, restrictedClients (drop the reverse-direction block for that side).","type":"array","items":{"type":"string","enum":["restrictedServiceProviders","restrictedConsumers","restrictedClients"]},"nullable":true},"disableOverride":{"description":"The single override key the user most recently unchecked; resets that field to its full default.","type":"string","example":"restrictedServiceProvider","nullable":true},"noOverride":{"description":"Echoes requirementAndPreferences back unchanged.","type":"boolean","nullable":true},"requirementAndPreferences":{"description":"Passed through/merged as-is; not validated here.","type":"array","items":{"properties":{"id":{"type":"string","nullable":true},"serviceType":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true},"skill":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true},"gender":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true},"clearance":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true},"specialization":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true},"certification":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true},"isDefault":{"type":"boolean","nullable":true}},"type":"object"},"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Preferences fetched successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Preferences fetched successfully."},"data":{"description":"Shape varies by mode (noOverride / isDefault / override). May include any of: requirementAndPreferences (echoed, noOverride only), timezone, priority {id, label}, userRestricted/userPreferred (arrays of {id, label}), and — when isDefault and locationType are both sent — default location fields.","type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"data":{"properties":{"client":{"type":"array","items":{"type":"string","example":"The selected client is invalid."}}},"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read|shifts:read","x-fido-module":"assignments","x-fido-roles":[],"x-fido-area":"Assignments","x-fido-area-rank":0}},"/v1/preference-list":{"get":{"tags":["Settings · Preferred Users"],"summary":"Retrieve paginated preference list with optional filters","description":"**Required scope:** `settings_preferred_users:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of preference list entries. Allows filtering, searching, and sorting.","operationId":"ext_get_preference_list","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"columns","in":"query","schema":{"type":"string"}},{"name":"sortBy","in":"query","schema":{"type":"string"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","schema":{"type":"integer"}},{"name":"clientId","in":"query","schema":{"type":"string"}},{"name":"consumerId","in":"query","schema":{"type":"string"}},{"name":"serviceProviderId","in":"query","schema":{"type":"string"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":2},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":20}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"object","example":{"search":["Invalid search parameter"]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:read","x-fido-module":"settings_preferred_users","x-fido-roles":["admin","scheduler"],"x-fido-area":"Preferred list","x-fido-area-rank":0},"post":{"tags":["Settings · Preferred Users"],"summary":"Create a new preference entry","operationId":"ext_post_preference_list","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["preferredBy","preferredUser"],"properties":{"preferredBy":{"required":["id","label"],"properties":{"id":{"description":"ID of the user adding the preference","type":"string","example":"CLT-EDFFGJ"},"label":{"description":"Role of the user adding the preference","type":"string","example":"Client"}},"type":"object"},"preferredUser":{"required":["id","label"],"properties":{"id":{"description":"ID of the user being preferred","type":"string","example":"SPR-EDUHU"},"label":{"description":"Role of the user being preferred","type":"string","example":"Service Provider"}},"type":"object"},"notes":{"description":"Optional notes for this preference","type":"string","example":"Demo"},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Preference successfully created","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"John Doe has been added to preferences by Jane Smith."}},"type":"object"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"preferredUser":["You can only prefer a Service Provider."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Preference list creation failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:write","x-fido-module":"settings_preferred_users","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_preferred_users:write`  \n**Roles:** admin, scheduler","x-fido-area":"Preferred list","x-fido-area-rank":0}},"/v1/preference-list-export":{"get":{"tags":["Settings · Preferred Users"],"summary":"Export preference list to Excel","description":"**Required scope:** `settings_preferred_users:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports the full preference list to an Excel (.xlsx) file for download.","operationId":"ext_get_preference_list_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing preference list data","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference list export failed. Please try again later."}},"type":"object"},"example":{"success":false,"message":"Preference list export failed. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:read","x-fido-module":"settings_preferred_users","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Preferred list","x-fido-area-rank":0}},"/v1/preference-list/{preference_list}":{"delete":{"tags":["Settings · Preferred Users"],"summary":"Delete a preference entry from the list","operationId":"ext_delete_preference_list_By_preference_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant-specific header key","required":true,"schema":{"type":"string","example":"tenant_abc"}},{"name":"preference_list","in":"path","description":"ID of the preference entry to delete","required":true,"schema":{"type":"integer","example":42}}],"responses":{"200":{"description":"Successfully removed from preference list","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"User has been removed from your preference list."}},"type":"object"}}}},"400":{"description":"Validation failed (e.g., invalid ID)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to delete."},"errors":{"type":"object","example":{"id":["The given ID is invalid or missing."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Preference deletion failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:delete","x-fido-module":"settings_preferred_users","x-fido-roles":[],"description":"**Required scope:** `settings_preferred_users:delete`","x-fido-area":"Preferred list","x-fido-area-rank":0},"get":{"tags":["Settings · Preferred Users"],"summary":"Retrieve a specific preference list entry","description":"**Required scope:** `settings_preferred_users:read`  \n**Roles:** admin, scheduler\n\nFetches a single preference list entry based on the provided ID.","operationId":"ext_get_preference_list_By_preference_list","parameters":[{"name":"preference_list","in":"path","description":"ID of the preference list entry","required":true,"schema":{"type":"integer","example":10}},{"name":"X-Tenant-ID","in":"header","description":"Tenant-specific header key","required":true,"schema":{"type":"string","example":"TNT-XYZ123"}}],"responses":{"200":{"description":"Preference entry retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Preference List entry retrieved."},"data":{"properties":{"id":{"type":"integer","example":1},"preferredUser":{"properties":{"id":{"type":"string","example":"SPR-AJKF8"},"label":{"type":"string","example":"John Service"}},"type":"object"},"preferredUserRoleName":{"type":"string","example":"admin","nullable":true},"preferredRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"preferredUserImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"preferredUserOnlineStatus":{"type":"string","example":"online"},"notes":{"type":"string","example":"Added by the scheduler."},"isBehalfOfOrg":{"type":"boolean","example":true},"preferredBy":{"properties":{"id":{"type":"string","example":"CLT-EDFFGJ"},"label":{"type":"string","example":"Client"}},"type":"object"},"preferredByOnlineStatus":{"type":"string","example":"online"},"preferredByRoleName":{"type":"string","example":"admin","nullable":true},"preferredByRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"preferredByImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Preference entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference List entry not found."},"errors":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Internal server exception message","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:read","x-fido-module":"settings_preferred_users","x-fido-roles":["admin","scheduler"],"x-fido-area":"Preferred list","x-fido-area-rank":0},"put":{"tags":["Settings · Preferred Users"],"summary":"Update a preference entry (notes, preferredBy, preferredUser)","operationId":"ext_put_preference_list_By_preference_list","parameters":[{"name":"preference_list","in":"path","description":"ID of the preference entry to update","required":true,"schema":{"type":"integer","example":123}},{"name":"X-Tenant-ID","in":"header","description":"Tenant Identifier","required":true,"schema":{"type":"string","example":"tenant_001"}}],"requestBody":{"description":"Any of the fields (notes, preferredBy, preferredUser) can be updated.","required":true,"content":{"application/json":{"schema":{"properties":{"preferredBy":{"properties":{"id":{"type":"integer","example":101},"label":{"type":"string","example":"John Doe"}},"type":"object"},"preferredUser":{"properties":{"id":{"type":"integer","example":202},"label":{"type":"string","example":"Jane Smith"}},"type":"object"},"notes":{"description":"Optional notes (max 255 characters)","type":"string","example":"Updated reason for preference"},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Preference entry updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Preference List updated!"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Preference entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:edit","x-fido-module":"settings_preferred_users","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_preferred_users:edit`  \n**Roles:** admin, scheduler","x-fido-area":"Preferred list","x-fido-area-rank":0},"patch":{"tags":["Settings · Preferred Users"],"summary":"Update a preference entry (notes, preferredBy, preferredUser)","operationId":"ext_patch_preference_list_By_preference_list","parameters":[{"name":"preference_list","in":"path","description":"ID of the preference entry to update","required":true,"schema":{"type":"integer","example":123}},{"name":"X-Tenant-ID","in":"header","description":"Tenant Identifier","required":true,"schema":{"type":"string","example":"tenant_001"}}],"requestBody":{"description":"Any of the fields (notes, preferredBy, preferredUser) can be updated.","required":true,"content":{"application/json":{"schema":{"properties":{"preferredBy":{"properties":{"id":{"type":"integer","example":101},"label":{"type":"string","example":"John Doe"}},"type":"object"},"preferredUser":{"properties":{"id":{"type":"integer","example":202},"label":{"type":"string","example":"Jane Smith"}},"type":"object"},"notes":{"description":"Optional notes (max 255 characters)","type":"string","example":"Updated reason for preference"},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Preference entry updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Preference List updated!"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Preference entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:edit","x-fido-module":"settings_preferred_users","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `settings_preferred_users:edit`  \n**Roles:** admin, scheduler","x-fido-area":"Preferred list","x-fido-area-rank":0}},"/v1/priorities":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve all priorities or filter by tenant ID","description":"**Required scope:** `settings_general:read` or `settings_service_setup:read`\n\nFetch a list of all priorities, or filter by a specific tenant ID if provided.","operationId":"ext_get_priorities","parameters":[{"name":"tenantId","in":"query","description":"Tenant ID for multi-tenant filtering.","required":false,"schema":{"type":"string","example":"demotenant"}}],"responses":{"200":{"description":"Priorities retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"value":1,"label":"Example label","isCustom":true}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":2}}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read|settings_service_setup:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Priorities","x-fido-area-rank":3},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new priority","description":"**Required scope:** `settings_service_setup:write`\n\nCreate a priority with a name and optional tenant association.","operationId":"ext_post_priorities","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","tenant_id"],"properties":{"name":{"type":"string","example":"Critical"},"tenant_id":{"type":"string","example":"demotenant"}},"type":"object"}}}},"responses":{"201":{"description":"Priority created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority created!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Priority created!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"400":{"description":"Validation error (e.g. missing required fields).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":[],"x-fido-area":"Priorities","x-fido-area-rank":3}},"/v1/priorities/{id}/{label}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a priority","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a priority by its ID.","operationId":"ext_delete_priorities_By_id_By_label","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"ID of the priority to delete.","required":true,"schema":{"type":"integer","example":7}},{"name":"label","in":"path","description":"Label of the priority to delete.","required":true,"schema":{"type":"string","example":"priority"}}],"responses":{"200":{"description":"Priority deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority deleted!"}},"type":"object"},"example":{"success":true,"message":"Priority deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Priority not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Priority with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Priority with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Priorities","x-fido-area-rank":3}},"/v1/priorities/{priority}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a priority by id alone (always 422)","description":"**Required scope:** `settings_service_setup:delete`\n\n**Use `/v1/priorities/{id}/{label}` instead.** This id-only form is registered by the resource route, but the handler identifies the record from a `label` path segment this route does not carry, so the call always fails validation with `label` required.","operationId":"ext_delete_priorities_By_priority","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"priority","in":"path","description":"ID of the priority.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed: the priority type could not be resolved from the URL.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The label field is required."}},"type":"object"},"example":{"status":"error","message":"The label field is required."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":[],"x-fido-area":"Priorities","x-fido-area-rank":3},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a single priority (not implemented)","description":"**Required scope:** `settings_general:read` or `settings_service_setup:read`\n\n**Not implemented.** The route is registered, but the controller action has no body, so the call succeeds with an empty response and no `{success, message, data}` envelope. Read the priority from the list endpoint `/v1/priorities` instead.","operationId":"ext_get_priorities_By_priority","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"priority","in":"path","description":"ID of the priority.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Empty body — the action is not implemented."},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read|settings_service_setup:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Priorities","x-fido-area-rank":3},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing priority","description":"**Required scope:** `settings_service_setup:edit`\n\nUpdate a priority by ID.","operationId":"ext_put_priorities_By_priority","parameters":[{"name":"priority","in":"path","description":"ID of the priority to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Critical"}},"type":"object"}}}},"responses":{"200":{"description":"Priority updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Priority updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Priority not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Priority with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Priority with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":[],"x-fido-area":"Priorities","x-fido-area-rank":3},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing priority","description":"**Required scope:** `settings_service_setup:edit`\n\nUpdate a priority by ID.","operationId":"ext_patch_priorities_By_priority","parameters":[{"name":"priority","in":"path","description":"ID of the priority to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Critical"}},"type":"object"}}}},"responses":{"200":{"description":"Priority updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Priority updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Priority not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Priority with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Priority with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":[],"x-fido-area":"Priorities","x-fido-area-rank":3}},"/v1/priority-based-broadcasts":{"get":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Retrieve paginated priority based broadcasts with optional filters","description":"**Required scope:** `settings_broadcast_dispatch:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of priority based broadcasts. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_priority_based_broadcasts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"High"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"Name","in":"query","description":"Search by name or ID","required":false,"schema":{"type":"string","example":"High"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Priority based broadcasts retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"priority":{"type":"string","nullable":true},"initialPoolSize":{"type":"integer","example":1,"nullable":true},"cycleInterval":{"type":"integer","example":1,"nullable":true},"cycleIntervalUnit":{"type":"string","example":"minutes","nullable":true},"maximumBroadcastRounds":{"type":"integer","example":1,"nullable":true},"escalationTimeout":{"type":"integer","example":1,"nullable":true},"escalationTimeoutUnit":{"type":"string","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:read","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Priority based broadcasts","x-fido-area-rank":0},"post":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Create a new priority based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:write`  \n**Roles:** admin, scheduler\n\nCreate a new priority based broadcast.","operationId":"ext_post_priority_based_broadcasts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["cycleInterval","cycleIntervalUnit","escalationTimeout","escalationTimeoutUnit","initialPoolSize","maximumBroadcastRounds","priority"],"properties":{"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"initialPoolSize":{"type":"integer","example":2},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"},"maximumBroadcastRounds":{"type":"integer","example":2},"escalationTimeout":{"type":"integer","example":2},"escalationTimeoutUnit":{"type":"string","example":"minutes"}},"type":"object"}}}},"responses":{"201":{"description":"Priority Based Broadcast created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority Based Broadcast created!"},"data":{"properties":{"id":{"type":"integer","example":1},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"initialPoolSize":{"type":"integer","example":2},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"},"maximumBroadcastRounds":{"type":"integer","example":2},"escalationTimeout":{"type":"integer","example":2},"escalationTimeoutUnit":{"type":"string","example":"minutes"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The priority field is required."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:write","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Priority based broadcasts","x-fido-area-rank":0}},"/v1/priority-based-broadcasts/{priority_based_broadcast}":{"delete":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Delete an priority based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:delete`  \n**Roles:** admin, scheduler\n\nDelete an priority based broadcast by its ID.","operationId":"ext_delete_priority_based_broadcasts_By_priority_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"priority_based_broadcast","in":"path","description":"ID of the priority based broadcast to delete.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Priority based broadcast deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority based broadcast deleted!"}},"type":"object"},"example":{"success":true,"message":"Priority based broadcast deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Priority based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Priority based broadcast with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Priority based broadcast with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:delete","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Priority based broadcasts","x-fido-area-rank":0},"get":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Retrieve a priority based broadcast by ID","description":"**Required scope:** `settings_broadcast_dispatch:read`  \n**Roles:** admin, scheduler\n\nFetch an priority based broadcast by its ID.","operationId":"ext_get_priority_based_broadcasts_By_priority_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"priority_based_broadcast","in":"path","description":"ID of priority based broadcast to retrieve.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Priority based broadcast retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority based broadcast retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"priority":{"type":"string","example":"string"},"initialPoolSize":{"type":"integer","example":1},"cycleInterval":{"type":"integer","example":1},"cycleIntervalUnit":{"type":"string","example":"minutes"},"maximumBroadcastRounds":{"type":"integer","example":1},"escalationTimeout":{"type":"integer","example":1},"escalationTimeoutUnit":{"type":"string","example":"string"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Priority based broadcast retrieved successfully!","data":{"id":1,"priority":"string","initialPoolSize":1,"cycleInterval":1,"cycleIntervalUnit":"minutes","maximumBroadcastRounds":1,"escalationTimeout":1,"escalationTimeoutUnit":"string"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Priority based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Priority based broadcast with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Priority based broadcast with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:read","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Priority based broadcasts","x-fido-area-rank":0},"put":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Update an existing priority based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing priority based broadcast by ID.","operationId":"ext_put_priority_based_broadcasts_By_priority_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"priority_based_broadcast","in":"path","description":"ID of the priority based broadcast to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"initialPoolSize":{"type":"integer","example":2},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"},"maximumBroadcastRounds":{"type":"integer","example":2},"escalationTimeout":{"type":"integer","example":2},"escalationTimeoutUnit":{"type":"string","example":"minutes"}},"type":"object"}}}},"responses":{"200":{"description":"Priority based broadcast updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority based broadcast updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"initialPoolSize":{"type":"integer","example":2},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"},"maximumBroadcastRounds":{"type":"integer","example":2},"escalationTimeout":{"type":"integer","example":2},"escalationTimeoutUnit":{"type":"string","example":"minutes"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Priority based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Priority based broadcast with ID 10 not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:edit","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Priority based broadcasts","x-fido-area-rank":0},"patch":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Update an existing priority based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing priority based broadcast by ID.","operationId":"ext_patch_priority_based_broadcasts_By_priority_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"priority_based_broadcast","in":"path","description":"ID of the priority based broadcast to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"initialPoolSize":{"type":"integer","example":2},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"},"maximumBroadcastRounds":{"type":"integer","example":2},"escalationTimeout":{"type":"integer","example":2},"escalationTimeoutUnit":{"type":"string","example":"minutes"}},"type":"object"}}}},"responses":{"200":{"description":"Priority based broadcast updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Priority based broadcast updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"initialPoolSize":{"type":"integer","example":2},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"},"maximumBroadcastRounds":{"type":"integer","example":2},"escalationTimeout":{"type":"integer","example":2},"escalationTimeoutUnit":{"type":"string","example":"minutes"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Priority based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Priority based broadcast with ID 10 not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:edit","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Priority based broadcasts","x-fido-area-rank":0}},"/v1/provider-delete/{id}":{"delete":{"tags":["Providers"],"summary":"Delete a service provider","description":"**Required scope:** `providers:delete`  \n**Roles:** admin, scheduler\n\nRemove the specified resource from storage.","operationId":"ext_delete_provider_delete_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID.","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"SPR-H6OUI3"}}],"responses":{"200":{"description":"Service provider deleted","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service provider deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"The provider does not exist.","content":{"application/json":{"schema":{"description":"Validation failures use their own envelope — status rather than success, and no code.","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages. Nested keys are collapsed onto the field the form renders.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error, or the provider cannot be deleted in its current state (the exception's own status code is used when it has one).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:delete","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider-update/{id}":{"post":{"tags":["Providers"],"summary":"Update a service provider","description":"**Required scope:** `providers:edit`  \n**Roles:** admin, scheduler\n\nUpdates a service provider by ID using the given payload.","operationId":"ext_post_provider_update_By_id","parameters":[{"name":"id","in":"path","description":"ID of the service provider to update","required":true,"schema":{"type":"string","example":"SPR-H6OUI3"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_001"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Same fields as create. Only the fields sent change.","properties":{"name":{"type":"string","maxLength":255,"example":"Sam Rivera"},"email":{"description":"Unique among this organization's users.","type":"string","format":"email","maxLength":255,"example":"sam@example.test"},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"status":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"serviceProviderRole":{"description":"Required when published. id is individual or agency.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"employmentStatus":{"description":"Required when published.","type":"string","enum":["full_time","part_time","contractor"],"nullable":true},"employmentStartDate":{"description":"Required when published.","type":"string","format":"date","nullable":true},"employmentEndDate":{"description":"On or after employmentStartDate.","type":"string","format":"date","nullable":true},"gender":{"description":"Required when published for an individual provider.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateOfBirth":{"description":"Optional.","type":"string","format":"date","nullable":true},"hearingStatus":{"description":"Required when published for an individual provider.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"portalAccess":{"description":"Let the provider sign in to the provider portal.","type":"boolean","nullable":true},"networkAccess":{"description":"Share the provider with the Fido network.","type":"boolean","nullable":true},"enableCalendarIntegration":{"type":"boolean","nullable":true},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required when published unless videoPhone is sent, and when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"phoneExtension":{"type":"string","maxLength":10,"nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"userPreferred":{"description":"Users this provider prefers.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"description":"Users restricted from this provider.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientRestricted":{"description":"Client users restricted from this provider.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"description":"Consumer users restricted from this provider.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"allowClientsToBroadcastImmediately":{"description":"Requests for this provider broadcast without scheduler review.","type":"boolean","nullable":true},"addressLine1":{"description":"Optional.","type":"string","maxLength":255,"nullable":true},"addressLine2":{"type":"string","maxLength":255,"nullable":true},"city":{"description":"Required when published.","type":"string","maxLength":100,"nullable":true},"state":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"Optional. 12345 or 12345-6789.","type":"string","example":"78759","nullable":true},"assignmentRequest":{"description":"Notification preference.","type":"boolean","nullable":true},"assignmentUpdates":{"description":"Notification preference.","type":"boolean","nullable":true},"serviceReminders":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"profileShareWithinOrganization":{"type":"boolean","nullable":true},"defaultServices":{"description":"Service type and provider type pairs the provider delivers. Each pair must be unique.","type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"isDefault":{"type":"boolean","nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"providerQualifications":{"description":"Certifications held, per service type and provider type.","type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"isDefault":{"type":"boolean","nullable":true},"serviceType":{"description":"One {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"serviceProviderType":{"description":"One {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"certification":{"type":"array","items":{"description":"One certification or clearance a provider holds.","properties":{"id":{"description":"Existing row to keep or update.","type":"integer","nullable":true},"serviceType":{"description":"The certification or clearance itself.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startDate":{"description":"Issue date. Required for a clearance.","type":"string","format":"date","nullable":true},"endDate":{"description":"Expiration date, after startDate. Required when the certification or clearance has expiration tracking on.","type":"string","format":"date","nullable":true},"file":{"description":"Proof document, max 2 MB. Required when the certification or clearance requires an upload.","type":"string","format":"binary","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"clearances":{"description":"One entry per clearance; serviceType holds the clearance.","type":"array","items":{"description":"One certification or clearance a provider holds.","properties":{"id":{"description":"Existing row to keep or update.","type":"integer","nullable":true},"serviceType":{"description":"The certification or clearance itself.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startDate":{"description":"Issue date. Required for a clearance.","type":"string","format":"date","nullable":true},"endDate":{"description":"Expiration date, after startDate. Required when the certification or clearance has expiration tracking on.","type":"string","format":"date","nullable":true},"file":{"description":"Proof document, max 2 MB. Required when the certification or clearance requires an upload.","type":"string","format":"binary","nullable":true}},"type":"object"},"nullable":true},"certifications":{"description":"Legacy flat list; serviceType holds the certification. The form sends providerQualifications instead.","type":"array","items":{"description":"One certification or clearance a provider holds.","properties":{"id":{"description":"Existing row to keep or update.","type":"integer","nullable":true},"serviceType":{"description":"The certification or clearance itself.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startDate":{"description":"Issue date. Required for a clearance.","type":"string","format":"date","nullable":true},"endDate":{"description":"Expiration date, after startDate. Required when the certification or clearance has expiration tracking on.","type":"string","format":"date","nullable":true},"file":{"description":"Proof document, max 2 MB. Required when the certification or clearance requires an upload.","type":"string","format":"binary","nullable":true}},"type":"object"},"nullable":true},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"availability":{"description":"Weekly office availability.","type":"array","items":{"properties":{"day":{"type":"string","example":"monday"},"isAvailable":{"type":"boolean","example":true},"slots":{"type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"17:00:00"}},"type":"object"}}},"type":"object"},"nullable":true},"vacations":{"description":"Time off. A vacation left out of an update is removed.","type":"array","items":{"properties":{"id":{"type":"integer","nullable":true},"reason":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date","example":"2025-07-01"},"endDate":{"type":"string","format":"date","example":"2025-07-04"},"startTime":{"type":"string","example":"00:00:00"},"endTime":{"type":"string","example":"23:59:00"}},"type":"object"},"nullable":true},"scheduleType":{"description":"Shape of dateTimeSlots.","type":"string","enum":["one_time","recurring","multi_day"],"nullable":true},"dateTimeSlots":{"type":"array","items":{"properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"17:00:00"}},"type":"object"},"nullable":true}},"type":"object"},"nullable":true},"maxAssignmentsPerWeek":{"type":"integer","nullable":true},"maxAssignmentsPerDay":{"type":"integer","nullable":true},"bufferBeforeMinutes":{"type":"integer","maximum":240,"minimum":0,"nullable":true},"bufferAfterMinutes":{"type":"integer","maximum":240,"minimum":0,"nullable":true},"travelRadius":{"description":"Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"preferredServiceLocations":{"description":"Required when published. id is onsite, remote or both.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timezone":{"type":"string","example":"America/Chicago","nullable":true},"defaultTimezone":{"description":"Localization. Required when published.","type":"string","example":"America/Chicago","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization. Required when published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization. Required when published.","type":"string","nullable":true},"startOfWeek":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startOfDay":{"description":"Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"Localization.","type":"string","example":"18:00","nullable":true},"restrictedClients":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedConsumers":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedServiceProviders":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"preferredClients":{"description":"Must not overlap restrictedClients.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"preferredConsumers":{"description":"Must not overlap restrictedConsumers.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"preferredServiceProviders":{"description":"Must not overlap restrictedServiceProviders.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"enableCustomRates":{"description":"Use the provider's own rates. Makes rates required.","type":"boolean","nullable":true},"rates":{"type":"array","items":{"description":"One custom rate. Rows not sent are deleted unless the save keeps unlisted rates.","properties":{"id":{"type":"integer","example":31,"nullable":true},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"rateType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"specialization":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignment":{"description":"The rate applies to assignments.","type":"boolean","example":true},"shift":{"description":"The rate applies to shifts.","type":"boolean","example":false},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","example":"hour","nullable":true},"minimumDuration":{"type":"number","example":2,"nullable":true}},"type":"object"},"nullable":true},"singleRates":{"type":"array","items":{"description":"The flat rate for one service type and provider type pair.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","format":"float","example":50,"nullable":true},"assignmentRateUnit":{"type":"string","example":"hour","nullable":true},"shiftEnabled":{"type":"boolean","example":false},"shiftRate":{"type":"number","format":"float","example":40,"nullable":true},"shiftRateUnit":{"type":"string","example":"hour","nullable":true}},"type":"object"},"nullable":true},"adminFee":{"type":"number","nullable":true},"adminFeeType":{"type":"string","enum":["assignment","shift","both"],"nullable":true},"providerAdminFeeMethod":{"type":"string","enum":["flat","percentage"],"nullable":true},"internalNotes":{"type":"string","nullable":true},"documents":{"description":"pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each.","type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Service provider updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service provider updated successfully."},"data":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"isDisableRole":{"description":"True when the roles payload turned the service-provider role off for this person.","type":"boolean","example":false},"messages":{"description":"Status-change notices from the save.","type":"array","items":{"type":"string"}}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The payload carries a Rates & Billing field (rates, single rates, admin fee, billing and cancellation terms) and the role has no Finance Edit, so nothing is saved. A payload without those fields follows the record's own permission alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"A field the caller may not change was sent with a new value (enableCalendarIntegration without admin, super-admin or a scheduler with Providers Edit), or validation failed. The field is named in errors. A rate unit other than Per Hour or Per Minute (for example weekly) in a rate or single-rate row is refused and nothing is saved; the message is under errors.unit, errors.assignmentRateUnit or errors.shiftRateUnit (no row index).","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed."},"errors":{"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error occurred","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:edit","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/document/files":{"delete":{"tags":["Providers"],"summary":"Delete files associated with a service provider","description":"**Required scope:** `providers:edit`  \n**Roles:** admin, scheduler\n\nDeletes uploaded document files tied to a service provider.","operationId":"ext_delete_provider_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["fileIds"],"properties":{"fileIds":{"description":"Array of service provider document IDs to delete","type":"array","items":{"type":"integer","example":8}}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully!"}},"type":"object"},"example":{"success":true,"message":"Files deleted successfully!"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Missing, non-array, or unknown fileIds.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"type":"object","example":{"fileIds":["Document ID is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:edit","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/export":{"get":{"tags":["Providers"],"summary":"Export service providers to Excel","description":"**Required scope:** `providers:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all service providers to an Excel file for download.","operationId":"ext_get_provider_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing all service providers","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/name-list":{"get":{"tags":["Providers"],"summary":"Get all service providers' names and IDs","description":"**Required scope:** `providers:read`  \n**Roles:** admin, scheduler\n\nFetches a list of all service providers with only their ID and name. Optionally filters by published status.","operationId":"ext_get_provider_name_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-QLRJVTKH"}},{"name":"isPublished","in":"query","description":"Filter by published status. If true, only published providers are returned. If false, only unpublished providers are returned. If omitted, all providers are returned.","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"List of Service Providers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Providers fetched successfully!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"John Doe"},"value":{"type":"string","example":"1"},"image":{"type":"string","example":"logo.png"}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Service Providers fetched successfully!","data":[{"id":"1","label":"John Doe","value":"1","image":"logo.png"},{"id":"2","label":"Jane Smith","value":"2","image":null}]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/qualification/files/{qualificationType}/{id}":{"delete":{"tags":["Providers"],"summary":"Delete a specific qualification file","description":"**Required scope:** `providers:edit`  \n**Roles:** admin, scheduler\n\nDeletes a qualification file (either clearance or certification) based on the qualification type and file ID.","operationId":"ext_delete_provider_qualification_files_By_qualificationType_By_id","parameters":[{"name":"qualificationType","in":"path","description":"Type of qualification (e.g., 'clearances' or 'certifications')","required":true,"schema":{"type":"string","enum":["clearances","certifications"],"example":"clearances"}},{"name":"id","in":"path","description":"ID of the qualification file to delete","required":true,"schema":{"type":"string","example":"123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Qualification file deleted successfully","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"clearances document 'SampleDocument.pdf' is deleted"}},"type":"object"},"example":{"message":"clearances document 'SampleDocument.pdf' is deleted"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"File not found or already deleted","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"File not found"}},"type":"object"},"example":{"message":"File not found"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:edit","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/qualification/{qualificationType}/{id}":{"delete":{"tags":["Providers"],"summary":"Delete a qualification record","description":"**Required scope:** `providers:edit`  \n**Roles:** admin, scheduler\n\nDeletes an entire qualification (either clearance or certification), including associated document(s), based on qualification type and ID.","operationId":"ext_delete_provider_qualification_By_qualificationType_By_id","parameters":[{"name":"qualificationType","in":"path","description":"Type of qualification (e.g., 'clearances' or 'certifications')","required":true,"schema":{"type":"string","enum":["clearances","certifications"],"example":"certifications"}},{"name":"id","in":"path","description":"ID of the qualification record to delete","required":true,"schema":{"type":"string","example":"456"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Qualification deleted successfully","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"certifications is deleted"}},"type":"object"},"example":{"message":"certifications is deleted"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Qualification record not found","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"Qualification not found"}},"type":"object"},"example":{"message":"Qualification not found"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:edit","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/single/export/{id}":{"get":{"tags":["Providers"],"summary":"Export a Service Provider to Excel","description":"**Required scope:** `providers:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports a single service provider's profile to an Excel file for download.","operationId":"ext_get_provider_single_export_By_id","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_001"}},{"name":"id","in":"path","description":"Unique identifier of the service provider to export.","required":true,"schema":{"type":"string","example":"SP-787"}}],"responses":{"200":{"description":"Excel file containing service provider data","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service provider not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service provider not found."}},"type":"object"},"example":{"success":false,"message":"Service provider not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/vacation/{id}":{"delete":{"tags":["Providers"],"summary":"Delete a service provider vacation list entry","description":"**Required scope:** `providers:edit`  \n**Roles:** super-admin, fido-admin, admin, scheduler\n\nDeletes a service provider vacation list entry by its ID. If the ID does not exist, a 404 error will be returned.","operationId":"ext_delete_provider_vacation_By_id","parameters":[{"name":"id","in":"path","description":"The ID of the service provider vacation list entry to delete","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":false,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Vacation deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service provider vacation entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected server error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:edit","x-fido-module":"providers","x-fido-roles":["super-admin","fido-admin","admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/provider/{id}/{tab}":{"get":{"tags":["Providers"],"summary":"Get a service provider's detail for one tab","description":"**Required scope:** `providers:read`  \n**Roles:** admin, scheduler\n\nReturns one tab's worth of a service provider's profile. The shape of `data` depends on which tab is requested.","operationId":"ext_get_provider_By_id_By_tab","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Organization tenant ID.","required":true,"schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"Service provider ID.","required":true,"schema":{"type":"string","example":"USR-AB12CD34"}},{"name":"tab","in":"path","description":"Which tab of the profile to return.","required":true,"schema":{"type":"string","enum":["details","qualifications","availability","requirement_and_preferences","rates_billing","localizations","assignmentStats"]}}],"responses":{"200":{"description":"Service provider detail retrieved successfully.","content":{"application/json":{"schema":{"description":"The payload follows the tab. historyLogs answers with a paginated envelope — success, data, meta and no message key; every other tab answers with success, message and a single data object. An unrecognized tab still answers 200, with data null.","properties":{"success":{"type":"boolean","example":true},"message":{"description":"Absent on the historyLogs tab.","type":"string","example":"Service Provider details retrieved successfully."},"data":{"description":"details, qualifications, availability, requirement_and_preferences, configuration, rates_billing, localizations and assignmentStats each return their own object; historyLogs returns an array of audit entries; an unknown tab returns null.","nullable":true,"oneOf":[{"type":"object"},{"type":"array","items":{"description":"One audit entry, on the historyLogs tab.","properties":{"id":{"type":"integer","example":1821},"event":{"type":"string","example":"updated","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"}}]},"meta":{"description":"Sent on the historyLogs tab only.","properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":24}},"type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The rates_billing tab is Finances data, so a role without Finance Read is refused it whatever it holds on the record's own module. Every other tab follows the record's module alone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Unknown id or tab.","content":{"application/json":{"schema":{"description":"Validation failures use their own envelope — status rather than success, and no code.","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages. Nested keys are collapsed onto the field the form renders.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["admin","scheduler"],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/rate-based-broadcasts":{"get":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Retrieve paginated rate based broadcasts with optional filters","description":"**Required scope:** `settings_broadcast_dispatch:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of rate based broadcasts. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_rate_based_broadcasts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"Standard"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"Name","in":"query","description":"Search by name or ID","required":false,"schema":{"type":"string","example":"Standard"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Rate based broadcasts retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"rate":{"type":"number","example":0},"cycleInterval":{"type":"integer","example":1,"nullable":true},"cycleIntervalUnit":{"type":"string","example":"minutes","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:read","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate based broadcasts","x-fido-area-rank":1},"post":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Create a new rate based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:write`  \n**Roles:** admin, scheduler\n\nCreate a new rate based broadcast with one or more rates.","operationId":"ext_post_rate_based_broadcasts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["rates","cycleInterval","cycleIntervalUnit"],"properties":{"rates":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Standard"}},"type":"object"}},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"}},"type":"object"}}}},"responses":{"201":{"description":"Rate Based Broadcast created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate Based Broadcast created!"},"data":{"properties":{"id":{"type":"integer","example":1},"rates":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"}},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The rates field is required."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:write","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate based broadcasts","x-fido-area-rank":1}},"/v1/rate-based-broadcasts/{rate_based_broadcast}":{"delete":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Delete a rate based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:delete`  \n**Roles:** admin, scheduler\n\nDelete a rate based broadcast by its ID.","operationId":"ext_delete_rate_based_broadcasts_By_rate_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"rate_based_broadcast","in":"path","description":"ID of the rate based broadcast to delete.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Rate based broadcast deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate based broadcast deleted!"}},"type":"object"},"example":{"success":true,"message":"Rate based broadcast deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Rate based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Rate based broadcast with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Rate based broadcast with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:delete","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate based broadcasts","x-fido-area-rank":1},"get":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Retrieve a rate based broadcast by ID","description":"**Required scope:** `settings_broadcast_dispatch:read`  \n**Roles:** admin, scheduler\n\nFetch a rate based broadcast by its ID.","operationId":"ext_get_rate_based_broadcasts_By_rate_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"rate_based_broadcast","in":"path","description":"ID of the rate-based broadcast to retrieve.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Rate based broadcast retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate based broadcast retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"rate":{"type":"number","example":0},"cycleInterval":{"type":"integer","example":1,"nullable":true},"cycleIntervalUnit":{"type":"string","example":"minutes","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Rate based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Rate based broadcast with ID 10 not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:read","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate based broadcasts","x-fido-area-rank":1},"put":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Update an existing rate based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing rate based broadcast by ID.","operationId":"ext_put_rate_based_broadcasts_By_rate_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"rate_based_broadcast","in":"path","description":"ID of the rate based broadcast to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"rates":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Standard"}},"type":"object"}},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"}},"type":"object"}}}},"responses":{"200":{"description":"Rate based broadcast updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate based broadcast updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"rates":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"}},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Rate based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Rate based broadcast with ID 10 not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:edit","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate based broadcasts","x-fido-area-rank":1},"patch":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Update an existing rate based broadcast","description":"**Required scope:** `settings_broadcast_dispatch:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing rate based broadcast by ID.","operationId":"ext_patch_rate_based_broadcasts_By_rate_based_broadcast","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"rate_based_broadcast","in":"path","description":"ID of the rate based broadcast to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"rates":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Standard"}},"type":"object"}},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"}},"type":"object"}}}},"responses":{"200":{"description":"Rate based broadcast updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate based broadcast updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"rates":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"}},"cycleInterval":{"type":"integer","example":2},"cycleIntervalUnit":{"type":"string","example":"hour"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Rate based broadcast not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Rate based broadcast with ID 10 not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:edit","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate based broadcasts","x-fido-area-rank":1}},"/v1/rates":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve paginated rates with optional filters","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of rates. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_rates","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"standard"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Rate Types retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"billingMethod":{"type":"string","nullable":true},"timeRange":{"type":"string"},"startTime":{"type":"string","example":"09:00:00","nullable":true},"endTime":{"type":"string","example":"09:00:00","nullable":true},"requestTiming":{"type":"string"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate types","x-fido-area-rank":6},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new rate type","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new rate type with a name and optional tenant ID.","operationId":"ext_post_rates","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"test"},"billingMethod":{"type":"string","example":"timeBased","nullable":true},"startTime":{"type":"string","format":"time","example":"11:15:00","nullable":true},"endTime":{"type":"string","format":"time","example":"11:20:00","nullable":true},"requestTiming":{"type":"integer","example":"1","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Rate type created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate type created!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"New rate type"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Rate type created!","data":{"id":10,"name":"New rate type","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate types","x-fido-area-rank":6}},"/v1/rates/{rate}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a rate","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a rate preference by ID.","operationId":"ext_delete_rates_By_rate","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"rate","in":"path","description":"ID of the rate to delete.","required":true,"schema":{"type":"integer","example":3}}],"responses":{"200":{"description":"Rate type deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate type deleted!"}},"type":"object"},"example":{"success":true,"message":"Rate type deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Rate type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Rate type with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Rate type with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate types","x-fido-area-rank":6},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a specific rate type","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a specific rate type by its ID.","operationId":"ext_get_rates_By_rate","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"rate","in":"path","description":"ID of the rate type to retrieve.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Rate type retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"billingMethod":{"type":"string","example":"string"},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"09:00:00"},"requestTiming":{"type":"string","example":"string"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Rate retrieved successfully!","data":{"id":1,"name":"Example name","billingMethod":"string","startTime":"09:00:00","endTime":"09:00:00","requestTiming":"string"}}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate types","x-fido-area-rank":6},"put":{"tags":["Settings · Service Setup"],"summary":"Update a rate type","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate a rate type with a name and optional tenant ID.","operationId":"ext_put_rates_By_rate","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"rate","in":"path","description":"ID of the rate to update.","required":true,"schema":{"type":"integer","example":4}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"test"},"billingMethod":{"type":"string","example":"timeBased","nullable":true},"startTime":{"type":"string","format":"time","example":"11:15:00","nullable":true},"endTime":{"type":"string","format":"time","example":"11:20:00","nullable":true},"requestTiming":{"type":"integer","example":"1","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Rate type updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate type updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"Updated rate type"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Rate type updated!","data":{"id":10,"name":"Updated rate type","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate types","x-fido-area-rank":6},"patch":{"tags":["Settings · Service Setup"],"summary":"Update a rate type","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate a rate type with a name and optional tenant ID.","operationId":"ext_patch_rates_By_rate","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"rate","in":"path","description":"ID of the rate to update.","required":true,"schema":{"type":"integer","example":4}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"test"},"billingMethod":{"type":"string","example":"timeBased","nullable":true},"startTime":{"type":"string","format":"time","example":"11:15:00","nullable":true},"endTime":{"type":"string","format":"time","example":"11:20:00","nullable":true},"requestTiming":{"type":"integer","example":"1","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Rate type updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rate type updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"Updated rate type"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Rate type updated!","data":{"id":10,"name":"Updated rate type","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate types","x-fido-area-rank":6}},"/v1/reassign-client-locations":{"post":{"tags":["Clients"],"summary":"Manage client location reassignment","description":"**Required scope:** `clients:edit`  \n**Roles:** admin, scheduler\n\nAllows reassigning, unassigning, or deleting additional client locations based on selected action.","operationId":"ext_post_reassign_client_locations","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"tenant_123"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["action","clientId"],"properties":{"action":{"description":"Action to perform on client's additional locations","type":"string","enum":["unassign","delete","reassign"],"example":"reassign"},"clientId":{"description":"Client ID whose additional locations need to be updated","type":"string","example":"CLT-101"},"reassignTo":{"description":"Target client ID to reassign locations to (required when action = reassign)","type":"string","example":"CLT-202","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Locations reassigned or updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Locations reassigned successfully"},"data":{"properties":{"clientId":{"type":"string","example":"CLT-101"},"action":{"type":"string","example":"reassign"},"reassignTo":{"type":"string","example":"CLT-202"},"updatedLocations":{"type":"integer","example":5}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Locations reassigned successfully","data":{"clientId":"CLT-101","action":"reassign","reassignTo":"CLT-202","updatedLocations":5}}}}},"400":{"description":"Invalid action or missing reassign target","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid action or reassignTo client ID missing when action is 'reassign'."}},"type":"object"},"example":{"success":false,"message":"Invalid action or reassignTo client ID missing when action is 'reassign'."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Client not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Client not found."}},"type":"object"},"example":{"success":false,"message":"Client not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:edit","x-fido-module":"clients","x-fido-roles":["admin","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/relationships":{"get":{"tags":["Settings · General"],"summary":"Retrieve paginated relationship with optional filters","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of relationship. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_relationships","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"student"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Relationship retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Relationships","x-fido-area-rank":7},"post":{"tags":["Settings · General"],"summary":"Create a new relationship","description":"**Required scope:** `settings_general:write`  \n**Roles:** admin, scheduler\n\nCreate a new relationship with a name and optional tenant ID.","operationId":"ext_post_relationships","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"New Relationship"}},"type":"object"}}}},"responses":{"201":{"description":"Relationship created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Relationship created!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"New Relationship"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Relationship created!","data":{"id":10,"name":"New Relationship","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Relationships","x-fido-area-rank":7}},"/v1/relationships/{relationship}":{"delete":{"tags":["Settings · General"],"summary":"Delete a relationship","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete a relationship by its ID.","operationId":"ext_delete_relationships_By_relationship","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"relationship","in":"path","description":"ID of the relationship to delete.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"200":{"description":"Relationship deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Relationship deleted!"}},"type":"object"},"example":{"success":true,"message":"Relationship deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Relationship not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Relationship not found."}},"type":"object"},"example":{"success":false,"message":"Relationship not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Relationships","x-fido-area-rank":7},"get":{"tags":["Settings · General"],"summary":"Retrieve a relationship by ID","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a relationship by its ID.","operationId":"ext_get_relationships_By_relationship","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"relationship","in":"path","description":"ID of the relationship to retrieve.","required":true,"schema":{"type":"integer","example":3}}],"responses":{"200":{"description":"Relationship retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Relationship retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Relationship retrieved successfully!","data":{"id":1,"name":{"id":1,"label":"Example label"}}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Relationship not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Relationship not found."}},"type":"object"},"example":{"success":false,"message":"Relationship not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Relationships","x-fido-area-rank":7},"put":{"tags":["Settings · General"],"summary":"Update an existing relationship","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing relationship by ID.","operationId":"ext_put_relationships_By_relationship","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"relationship","in":"path","description":"ID of the relationship to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Relationship"}},"type":"object"}}}},"responses":{"200":{"description":"Relationship updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Relationship updated!"},"data":{"properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"Updated Relationship"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Relationship updated!","data":{"id":5,"name":"Updated Relationship","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Relationship not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Relationship with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Relationship with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Relationships","x-fido-area-rank":7},"patch":{"tags":["Settings · General"],"summary":"Update an existing relationship","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing relationship by ID.","operationId":"ext_patch_relationships_By_relationship","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"relationship","in":"path","description":"ID of the relationship to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Relationship"}},"type":"object"}}}},"responses":{"200":{"description":"Relationship updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Relationship updated!"},"data":{"properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"Updated Relationship"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Relationship updated!","data":{"id":5,"name":"Updated Relationship","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Relationship not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Relationship with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Relationship with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Relationships","x-fido-area-rank":7}},"/v1/request-statuses":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve paginated request statuses with optional filters","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of request statuses. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_request_statuses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"completed"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"Name","in":"query","description":"Search by name or ID","required":false,"schema":{"type":"string","example":"Completed"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Request statuses retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"description":{"type":"string","example":"Short human-readable description.","nullable":true},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"isCustom":{"type":"boolean","example":true},"children":{"type":"array","items":[]}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Request statuses","x-fido-area-rank":7},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new request status","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new request statuse with a name,description and parent.","operationId":"ext_post_request_statuses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"New Request Status"},"description":{"type":"string","example":"This is test description for new request status.","nullable":true},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Request status created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request status created!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"New request status"},"description":{"type":"string","example":"This is test description for new request status."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Request status created!","data":{"id":10,"name":"New request status","description":"This is test description for new request status.","parent":{"id":1,"label":"Pending"},"isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Request statuses","x-fido-area-rank":7}},"/v1/request-statuses/{request_status}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete an request status","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete an request status by its ID.","operationId":"ext_delete_request_statuses_By_request_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"request_status","in":"path","description":"ID of the request status to delete.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Request status deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request status deleted!"}},"type":"object"},"example":{"success":true,"message":"Request status deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Request status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Request status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Request status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Request statuses","x-fido-area-rank":7},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve an request status by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch an request status by its ID.","operationId":"ext_get_request_statuses_By_request_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"request_status","in":"path","description":"ID of request status to retrieve.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Request status retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request status retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"description":{"type":"string","example":"Short human-readable description."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Request status retrieved successfully!","data":{"id":1,"name":"Example name","description":"Short human-readable description.","parent":{"id":1,"label":"Example label"},"isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Request status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Request status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Request status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Request statuses","x-fido-area-rank":7},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing request status","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing request status by ID.","operationId":"ext_put_request_statuses_By_request_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"request_status","in":"path","description":"ID of the request status to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated request status"},"description":{"type":"string","example":"This is test description for updated request status.","nullable":true},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Request status updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request status updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"Updated request status"},"description":{"type":"string","example":"This is test description for updated request status."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Request status updated!","data":{"id":10,"name":"Updated request status","description":"This is test description for updated request status.","parent":{"id":1,"label":"Pending"},"isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Request status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Request status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Request status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Request statuses","x-fido-area-rank":7},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing request status","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing request status by ID.","operationId":"ext_patch_request_statuses_By_request_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"request_status","in":"path","description":"ID of the request status to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated request status"},"description":{"type":"string","example":"This is test description for updated request status.","nullable":true},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Request status updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request status updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"Updated request status"},"description":{"type":"string","example":"This is test description for updated request status."},"parent":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Pending"}},"type":"object"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Request status updated!","data":{"id":10,"name":"Updated request status","description":"This is test description for updated request status.","parent":{"id":1,"label":"Pending"},"isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Request status not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Request status with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Request status with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Request statuses","x-fido-area-rank":7}},"/v1/requirement-preferences":{"get":{"tags":["Settings · General"],"summary":"Retrieve a list of requirement preferences","description":"**Required scope:** `settings_general:read`\n\nFetch a list of available requirement preferences.","operationId":"ext_get_requirement_preferences","parameters":[{"name":"tenantId","in":"query","description":"Tenant ID. Used for multi-tenant authentication.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Requirement preferences retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Requirement preferences Retrieved!"},"data":{"properties":{"skills":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Basic"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"certifications":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"RID"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"clearances":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"HIPAA"},"isCustom":{"type":"boolean","example":false}},"type":"object"}},"insurances":{"description":"The organization's insurance list (Settings → Service Setup → Insurance). Empty without tenantId: there is no central catalog.","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"General Liability"},"isCustom":{"type":"boolean","example":null,"nullable":true},"serviceId":{"description":"The service type the entry is for.","type":"integer","example":1},"serviceProviderTypeId":{"description":"The service provider type the entry is for.","type":"integer","example":2},"uploadRequired":{"type":"boolean","example":true},"expireDateRequired":{"type":"boolean","example":true}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"},"isCustom":{"type":"boolean","example":false}},"type":"object"}}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Requirement preferences Retrieved!","data":{"skills":[{"id":1,"value":1,"label":"Basic","isCustom":false},{"id":2,"value":2,"label":"Advanced","isCustom":false}],"certifications":[{"id":1,"value":1,"label":"RID","isCustom":false},{"id":2,"value":2,"label":"NIC","isCustom":false}],"clearances":[{"id":1,"value":1,"label":"HIPAA","isCustom":false},{"id":2,"value":2,"label":"Background Check","isCustom":false}],"specializations":[{"id":1,"value":1,"label":"Legal","isCustom":false},{"id":2,"value":2,"label":"Medical","isCustom":false}]}}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Requirements and preferences","x-fido-area-rank":10}},"/v1/roles":{"get":{"tags":["Team"],"summary":"Fetch all roles","description":"**Required scope:** `team:read`\n\nFetches all available roles with their ID, label, value, and slug.","operationId":"ext_get_roles","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-NRLWQEDM"}}],"responses":{"200":{"description":"Roles fetched successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Roles fetched successfully"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Client"},"value":{"type":"string","example":"1"},"slug":{"type":"string","example":"client"}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Something went wrong","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Error Fetching Roles: ...","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:read","x-fido-module":"team","x-fido-roles":[],"x-fido-area":"Roles and users","x-fido-area-rank":1}},"/v1/schedule/assign-provider":{"post":{"tags":["Schedule"],"summary":"Assign service providers to assignment(s) or shift(s)","description":"**Required scope:** `schedule:read`  \n**Roles:** admin, scheduler\n\nAssign one or more service providers to one or more assignments or shifts. Supports multiple service types and location types per provider.","operationId":"ext_post_schedule_assign_provider","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}}],"requestBody":{"description":"Assignment or shift provider assignment payload","required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"Type of entity to assign providers to","type":"string","enum":["assignment","shift"],"example":"assignment"},"assignmentId":{"description":"Array of assignment IDs (required if type=assignment)","type":"array","items":{"type":"string","example":"ASG-XDMSDH"}},"shiftId":{"description":"Array of shift IDs (required if type=shift)","type":"array","items":{"type":"string","example":"SFT-8Z13C5"}},"assignProviders":{"description":"List of providers to assign","type":"array","items":{"properties":{"id":{"description":"Service provider ID","type":"string","example":"SPR-M8F6NP"}},"type":"object"}},"method":{"description":"How providers should be assigned: direct assigns immediately, accept/express-interest place the provider in pending status","type":"string","enum":["direct","accept","express-interest"],"example":"direct"},"locationType":{"description":"Location type(s) to assign the provider under (also accepts a single string). Each service type is assigned under whichever of these locations offers it. When omitted, all assignment/shift locations are considered","type":"array","items":{"type":"string","enum":["onsite","remote"],"example":"onsite"}},"serviceType":{"description":"Service type IDs to assign providers under for this request","type":"array","items":{"type":"integer","example":1}},"serviceProviderType":{"description":"Service provider type ID(s), e.g. Hearing Interpreter (also accepts a single integer). Each is only applied to the serviceType it actually belongs to, and at most one provider type is assigned per service type","type":"array","items":{"type":"integer","example":2}}},"type":"object"}}}},"responses":{"201":{"description":"Providers assigned successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Providers assigned successfully."},"data":{"properties":{"ids":{"description":"List of assignment or shift IDs that were processed","type":"array","items":{"type":"string","example":"ASG-XDMSDH"}}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad request or missing parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Missing assignment/shift ID(s) or providers data."},"errors":{"type":"string","example":"Invalid Request"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Service provider assignment failed.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read","x-fido-module":"schedule","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assign and availability","x-fido-area-rank":0}},"/v1/schedule/assignments-and-shifts":{"post":{"tags":["Schedule"],"summary":"Get schedule assignments or shifts with availability matching","description":"**Required scope:** `schedule:read`  \n**Roles:** admin, scheduler\n\nRetrieve unfilled assignments or shifts matching location, service types, and provider availability with partial coverage support","operationId":"ext_post_schedule_assignments_and_shifts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"startDate":{"type":"string","format":"date","example":"2025-11-01"},"endDate":{"type":"string","format":"date","example":"2025-11-30"},"startTime":{"description":"Filter whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime.","type":"string","format":"time","example":"09:00:00"},"endTime":{"description":"Filter whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","type":"string","format":"time","example":"17:00:00"},"locationType":{"type":"string","enum":["remote","onsite","hybrid"],"example":"onsite"},"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"providerId":{"description":"Excludes assignments/shifts this provider is already assigned to","type":"string","example":"SP-XDMSDH"},"serviceTypes":{"type":"array","items":{"type":"integer"},"example":[1,2,3]},"availability":{"type":"array","items":{"properties":{"day":{"type":"string","example":"Tuesday"},"date":{"type":"string","format":"date","example":"2025-11-04"},"startTime":{"type":"string","example":"14:00"},"endTime":{"type":"string","example":"16:00"}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Assignments or shifts retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignments retrieved successfully"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-XDMSDH"},"label":{"type":"string","example":"Home Care Assignment"},"startDate":{"type":"string","example":"2025-11-01"},"endDate":{"type":"string","example":"2025-11-30"}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read","x-fido-module":"schedule","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments and shifts on the schedule","x-fido-area-rank":2}},"/v1/schedule/assignments-and-shifts/{id}/{type}":{"get":{"tags":["Schedule"],"summary":"Get assignment or shift details","description":"**Required scope:** `schedule:read`  \n**Roles:** admin, scheduler\n\nRetrieve assignment or shift details including client, consumers, location, service types, and requirements","operationId":"ext_get_schedule_assignments_and_shifts_By_id_By_type","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"id","in":"path","description":"Assignment or Shift ID","required":true,"schema":{"type":"string","example":"SFT-2XIM11"}},{"name":"type","in":"path","description":"Type of data to retrieve","required":true,"schema":{"type":"string","enum":["assignment","shift"],"example":"shift"}}],"responses":{"200":{"description":"Assignment or shift data retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Retrieved shift data successfully"},"data":{"properties":{"client":{"properties":{"id":{"type":"string","example":"CLT-GGM6R1"},"label":{"type":"string","example":"Client1"}},"type":"object","nullable":true},"assignClient":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-HW3EPL"},"label":{"type":"string","example":"Client14"}},"type":"object"}},"consumer":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-MUQVGB"},"label":{"type":"string","example":"Consumer5"}},"type":"object"}},"assignTo":{"type":"string","example":"organization"},"locationType":{"type":"string","example":"onsite"},"onsite":{"properties":{"onSiteType":{"type":"string","example":"organization"},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"providerTypeBreakdown":{"type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Hearing"}},"type":"object"}},"certifications":{"type":"array","items":{"properties":{"id":{"type":"integer","example":4},"label":{"type":"string","example":"BEI Basic"}},"type":"object"}},"skills":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Basic"}},"type":"object"}},"clearances":{"type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Background Check"}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"}}},"type":"object"}}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read","x-fido-module":"schedule","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignments and shifts on the schedule","x-fido-area-rank":2}},"/v1/schedule/calendar/assignments":{"get":{"tags":["Assignments"],"summary":"Retrieve a list of assignments","description":"**Required scope:** `schedule:read` and `assignments:read`\n\nFetches a list of assignments based on status search criteria. For a service provider who holds only part of a partial-coverage job, start and end span their own hours (first covered start to last covered end); every other role is unchanged.","operationId":"ext_get_schedule_calendar_assignments","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"status","in":"query","description":"Comma-separated list of assignment-status IDs, e.g. `1,2,3` — a single ID\n    works too. This mirrors the calendar's status checkboxes: the response contains only the statuses\n    you list, and omitting the parameter (or sending it empty) returns an empty list rather than\n    everything, matching an all-unchecked filter. Each ID is matched exactly — a parent status does\n    not pull in its children, so list every status you want. Statuses are tenant-configurable rows,\n    not a fixed vocabulary, so there is no enum here and the example is an example, not a contract —\n    read the valid IDs for this tenant from GET /assignment-statuses. A hard-coded value will go stale\n    the moment a tenant edits its statuses.","required":false,"schema":{"type":"string","example":"1,2,3,4,5,6,7"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter assignments by scheduled start date on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter assignments by scheduled end date on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}}],"responses":{"200":{"description":"Assignments retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignments Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-XY9EML"},"title":{"type":"string","example":"Example title","nullable":true},"start":{"type":"string","example":"2026-01-15","nullable":true},"end":{"type":"string","example":"2026-01-15","nullable":true},"convertedStart":{"type":"string","example":"2026-01-15 09:00 AM","nullable":true},"convertedEnd":{"type":"string","example":"2026-01-15 09:00 AM","nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object","nullable":true},"type":{"type":"string","example":"assignments"}},"type":"object"}}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read assignments:read","x-fido-module":"schedule","x-fido-roles":[],"x-fido-area":"Calendar","x-fido-area-rank":4}},"/v1/schedule/calendar/assignments/{id}":{"get":{"tags":["Assignments"],"summary":"Retrieve details of a assignment for calendar","description":"**Required scope:** `schedule:read` and `assignments:read`\n\nFetches the details of a assignment, based on the provided assignment ID. For a service provider who holds only part of a partial-coverage job, myTime and myConvertedTime carry their own covered hours (same format as time and convertedTime, separate runs joined with ', '); they are null for everyone else. Each serviceProviders entry adds coveredTime, the hours that provider holds, or null when they hold the whole job.","operationId":"ext_get_schedule_calendar_assignments_By_id","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Assignment details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"string","example":"ASG-XY9EML"},"title":{"type":"string","example":"Example title"},"client":{"properties":{"id":{"type":"string","example":"CLT-XWB2RY"},"name":{"type":"string","example":"Example name"},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"}},"type":"object"},"clientType":{"type":"string","example":"Individual"},"clientIndustry":{"type":"array","items":{"type":"object"}},"consumer":{"type":"array","items":{"type":"object"}},"scheduleType":{"type":"string","example":"one_time"},"locationType":{"type":"string","example":"string"},"start":{"type":"string","format":"date","example":"2026-01-15"},"end":{"type":"string","format":"date","example":"2026-01-15"},"convertedStart":{"type":"string","format":"date-time","example":"2026-01-15 09:00 AM"},"convertedEnd":{"type":"string","format":"date-time","example":"2026-01-15 09:00 AM"},"convertedStartDate":{"type":"string","format":"date","example":"2026-01-15"},"convertedEndDate":{"type":"string","format":"date","example":"2026-01-15"},"day":{"type":"string","example":"string"},"convertedDay":{"type":"string","example":"string"},"endDay":{"type":"string","example":"string"},"convertedEndDay":{"type":"string","example":"string"},"date":{"type":"string","format":"date","example":"2026-01-15"},"convertedDate":{"type":"string","format":"date","example":"2026-01-15"},"time":{"type":"string","format":"time","example":"09:00:00"},"convertedTime":{"type":"string","format":"time","example":"09:00:00"},"formateStartTime":{"type":"string","format":"time","example":"09:00:00"},"formateEndTime":{"type":"string","format":"time","example":"09:00:00"},"formateStartDate":{"type":"string","format":"date","example":"2026-01-15"},"formateEndDate":{"type":"string","format":"date","example":"2026-01-15"},"userTimezone":{"type":"string","example":"America/New_York"},"assignmentTimezone":{"type":"string","example":"America/New_York"},"userDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"onsite":{"properties":{"onsiteType":{"type":"string","example":"string"}},"type":"object"},"remote":{"properties":{"remoteType":{"type":"string","example":"string"},"remoteMeetingLink":{"type":"string","example":"https://example.com"},"remoteMeetingPlatform":{"type":"string","example":"Virtual link provided"},"onDemandLink":{"type":"string","example":"https://example.com"},"onDemandAccessInstructions":{"type":"string","example":"string"}},"type":"object"},"serviceTypes":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviders":{"type":"string","example":"string"},"groupedProvider":{"type":"string","example":"string"},"status":{"type":"array","items":{"type":"object"}},"requestGroupedConsumer":{"type":"array","items":{"type":"object"}},"statusMethod":{"type":"string","example":"string"},"assignmentMethod":{"type":"string","example":"string"},"dontAskMeAgain":{"type":"string","example":"string"},"parentId":{"type":"string","example":"string"},"redirectTo":{"type":"string","example":"assignments"},"canConsumerEdit":{"type":"boolean","example":true},"confirmedTimeSlots":{"type":"string","example":"string"},"restrictedActionButtons":{"type":"array","items":{"type":"object"}},"missingRates":{"type":"array","items":{"type":"object"}},"hasRateMissing":{"type":"boolean","example":true},"requiresTimeSlotPopup":{"type":"boolean","example":true},"isCompleted":{"type":"boolean","example":true},"isPast":{"type":"boolean","example":true},"showRestrictedWarning":{"type":"boolean","example":true},"restrictedWarningMessage":{"type":"string","example":"This action is restricted for the assigned provider."}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":"ASG-XY9EML","title":"Example title","client":{"id":"CLT-XWB2RY","name":"Example name","image":"https://cdn.example.com/image.png","onlineStatus":"online"},"clientType":"Individual","clientIndustry":[],"consumer":[],"scheduleType":"one_time","locationType":"string","start":"2026-01-15","end":"2026-01-15","convertedStart":"2026-01-15 09:00 AM","convertedEnd":"2026-01-15 09:00 AM","convertedStartDate":"2026-01-15","convertedEndDate":"2026-01-15","day":"string","convertedDay":"string","endDay":"string","convertedEndDay":"string","date":"2026-01-15","convertedDate":"2026-01-15","time":"09:00:00","convertedTime":"09:00:00","formateStartTime":"09:00:00","formateEndTime":"09:00:00","formateStartDate":"2026-01-15","formateEndDate":"2026-01-15","userTimezone":"America/New_York","assignmentTimezone":"America/New_York","userDateTooltip":"Jan 15, 2026 9:00 AM – 11:00 AM","onsite":{"onsiteType":"string"},"remote":{"remoteType":"string","remoteMeetingLink":"https://example.com","remoteMeetingPlatform":"Virtual link provided","onDemandLink":"https://example.com","onDemandAccessInstructions":"string"},"serviceTypes":{"id":1,"label":"Example label"},"serviceProviders":"string","groupedProvider":"string","status":[],"requestGroupedConsumer":[],"statusMethod":"string","assignmentMethod":"string","dontAskMeAgain":"string","parentId":"string","redirectTo":"assignments","canConsumerEdit":true,"confirmedTimeSlots":"string","restrictedActionButtons":[],"missingRates":[],"hasRateMissing":true,"requiresTimeSlotPopup":true,"isCompleted":true,"isPast":true,"showRestrictedWarning":true,"restrictedWarningMessage":"This action is restricted for the assigned provider."}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified assignment does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified assignment does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read assignments:read","x-fido-module":"schedule","x-fido-roles":[],"x-fido-area":"Calendar","x-fido-area-rank":4}},"/v1/schedule/calendar/org-provider-availability":{"get":{"tags":["Schedule"],"summary":"Get organization or service provider availability","description":"**Required scope:** `schedule:read` and `providers:read`\n\nRetrieve availability for organization office hours or authenticated service provider with detailed time slots","operationId":"ext_get_schedule_calendar_org_provider_availability","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date (defaults to today)","required":false,"schema":{"type":"string","format":"date","example":"2025-11-28"}},{"name":"endDate","in":"query","description":"End date (defaults to today)","required":false,"schema":{"type":"string","format":"date","example":"2025-11-28"}},{"name":"startTime","in":"query","description":"Filter whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime.","required":false,"schema":{"type":"string","format":"time","example":"09:00:00"}},{"name":"endTime","in":"query","description":"Filter whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","required":false,"schema":{"type":"string","format":"time","example":"17:00:00"}},{"name":"availability","in":"query","description":"Filter by availability status: available, unavailable, or both (comma-separated)","required":false,"schema":{"type":"string","example":"available,unavailable"}}],"responses":{"200":{"description":"Availability retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Availability retrieved successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read providers:read","x-fido-module":"schedule","x-fido-roles":[],"x-fido-area":"Assign and availability","x-fido-area-rank":0}},"/v1/schedule/calendar/requests":{"get":{"tags":["Assignments"],"summary":"Retrieve a list of requests","description":"**Required scope:** `schedule:read` and `assignments:read`\n\nFetches a list of request based on status search criteria.","operationId":"ext_get_schedule_calendar_requests","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"status","in":"query","description":"Filter request by status enum.","required":false,"schema":{"type":"string","example":"submitted"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter requests by scheduled start date on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter requests by scheduled end date on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}}],"responses":{"200":{"description":"Requests retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Requests Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-XY9EML"},"title":{"type":"string","example":"Example title","nullable":true},"start":{"type":"string","example":"2026-01-15","nullable":true},"end":{"type":"string","example":"2026-01-15","nullable":true},"convertedStart":{"type":"string","example":"2026-01-15 09:00 AM","nullable":true},"convertedEnd":{"type":"string","example":"2026-01-15 09:00 AM","nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object","nullable":true},"type":{"type":"string","example":"assignments"}},"type":"object"}}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read assignments:read","x-fido-module":"schedule","x-fido-roles":[],"x-fido-area":"Calendar","x-fido-area-rank":4}},"/v1/schedule/calendar/shifts":{"get":{"tags":["Shifts"],"summary":"Retrieve a list of shift","description":"**Required scope:** `schedule:read` and `shifts:read`  \n**Roles:** admin, scheduler\n\nFetches a paginated list of shifts based on search criteria, filters, and sorting options. For a service provider who holds only part of a partial-coverage job, start and end span their own hours (first covered start to last covered end); every other role is unchanged.","operationId":"ext_get_schedule_calendar_shifts","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"status","in":"query","description":"Comma-separated list of shift-status IDs, e.g. `1,2,3` — a single ID works\n    too. This mirrors the calendar's status checkboxes: omitting the parameter (or sending it empty)\n    returns an empty list rather than every shift. Each ID is matched exactly — a parent status does\n    not pull in its children. Statuses are tenant-configurable rows, so read the valid IDs for this\n    tenant rather than hard-coding them.","required":false,"schema":{"type":"string","example":"1,2,3,4,5,6,7"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter shift created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter shift created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}}],"responses":{"200":{"description":"Shifts retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shifts Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-XY9EML"},"title":{"type":"string","example":"Example title","nullable":true},"start":{"type":"string","example":"2026-01-15","nullable":true},"end":{"type":"string","example":"2026-01-15","nullable":true},"convertedStart":{"type":"string","example":"2026-01-15 09:00 AM","nullable":true},"convertedEnd":{"type":"string","example":"2026-01-15 09:00 AM","nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label","nullable":true}},"type":"object","nullable":true},"type":{"type":"string","example":"assignments"}},"type":"object"}}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read shifts:read","x-fido-module":"schedule","x-fido-roles":["admin","scheduler"],"x-fido-area":"Calendar","x-fido-area-rank":2}},"/v1/schedule/calendar/shifts/{id}":{"get":{"tags":["Shifts"],"summary":"Retrieve details of a shift for calendar","description":"**Required scope:** `schedule:read` and `shifts:read`\n\nFetches the details of a shift, based on the provided shift ID. For a service provider who holds only part of a partial-coverage job, myTime and myConvertedTime carry their own covered hours (same format as time and convertedTime, separate runs joined with ', '); they are null for everyone else. Each serviceProviders entry adds coveredTime, the hours that provider holds, or null when they hold the whole job.","operationId":"ext_get_schedule_calendar_shifts_By_id","parameters":[{"name":"id","in":"path","description":"Unique identifier of the assignment","required":true,"schema":{"type":"string","example":"SFT-ZGJ8T2"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Shift details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"string","example":"SFT-MNP4PJ"},"title":{"type":"string","example":"Example title"},"shiftBlock":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"09:00:00"}},"type":"object"},"client":{"properties":{"id":{"type":"string","example":"SPR-FG543C"},"name":{"type":"string","example":"Example name"},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"}},"type":"object"},"assignClient":{"type":"array","items":{"type":"object"}},"assignClientLocation":{"type":"array","items":{"type":"object"}},"scheduleType":{"type":"string","example":"one_time"},"locationType":{"type":"string","example":"string"},"start":{"type":"string","format":"date","example":"2026-01-15"},"end":{"type":"string","format":"date","example":"2026-01-15"},"convertedStart":{"type":"string","format":"date-time","example":"2026-01-15 09:00 AM"},"convertedEnd":{"type":"string","format":"date-time","example":"2026-01-15 09:00 AM"},"convertedStartDate":{"type":"string","format":"date","example":"2026-01-15"},"convertedEndDate":{"type":"string","format":"date","example":"2026-01-15"},"day":{"type":"string","example":"string"},"convertedDay":{"type":"string","example":"string"},"endDay":{"type":"string","example":"string"},"convertedEndDay":{"type":"string","example":"string"},"date":{"type":"string","format":"date","example":"2026-01-15"},"convertedDate":{"type":"string","format":"date","example":"2026-01-15"},"time":{"type":"string","format":"time","example":"09:00:00"},"convertedTime":{"type":"string","format":"time","example":"09:00:00"},"userTimezone":{"type":"string","example":"America/New_York"},"formateStartTime":{"type":"string","format":"time","example":"09:00:00"},"formateEndTime":{"type":"string","format":"time","example":"09:00:00"},"formateStartDate":{"type":"string","format":"date","example":"2026-01-15"},"formateEndDate":{"type":"string","format":"date","example":"2026-01-15"},"assignmentTimezone":{"type":"string","example":"America/New_York"},"userDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"onsite":{"properties":{"onsiteType":{"type":"string","example":"string"}},"type":"object"},"remote":{"properties":{"remoteType":{"type":"string","example":"string"},"remoteMeetingLink":{"type":"string","example":"https://example.com"},"remoteMeetingPlatform":{"type":"string","example":"Virtual link provided"},"onDemandLink":{"type":"string","example":"https://example.com"},"onDemandAccessInstructions":{"type":"string","example":"string"}},"type":"object"},"serviceTypes":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviders":{"type":"string","example":"string"},"groupedProvider":{"type":"string","example":"string"},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"statusMethod":{"type":"string","example":"string"},"assignmentMethod":{"type":"string","example":"string"},"dontAskMeAgain":{"type":"string","example":"string"},"parentId":{"type":"string","example":"string"},"redirectTo":{"type":"string","example":"shifts"},"confirmedTimeSlots":{"type":"string","example":"string"},"restrictedActionButtons":{"type":"array","items":{"type":"object"}},"missingRates":{"type":"array","items":{"type":"object"}},"hasRateMissing":{"type":"boolean","example":true},"requiresTimeSlotPopup":{"type":"boolean","example":true},"isCompleted":{"type":"boolean","example":true},"isPast":{"type":"boolean","example":true},"showRestrictedWarning":{"type":"boolean","example":true},"restrictedWarningMessage":{"type":"string","example":"This action is restricted for the assigned provider."}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":"SFT-MNP4PJ","title":"Example title","shiftBlock":{"id":1,"label":"Example label","startTime":"09:00:00","endTime":"09:00:00"},"client":{"id":"SPR-FG543C","name":"Example name","image":"https://cdn.example.com/image.png","onlineStatus":"online"},"assignClient":[],"assignClientLocation":[],"scheduleType":"one_time","locationType":"string","start":"2026-01-15","end":"2026-01-15","convertedStart":"2026-01-15 09:00 AM","convertedEnd":"2026-01-15 09:00 AM","convertedStartDate":"2026-01-15","convertedEndDate":"2026-01-15","day":"string","convertedDay":"string","endDay":"string","convertedEndDay":"string","date":"2026-01-15","convertedDate":"2026-01-15","time":"09:00:00","convertedTime":"09:00:00","userTimezone":"America/New_York","formateStartTime":"09:00:00","formateEndTime":"09:00:00","formateStartDate":"2026-01-15","formateEndDate":"2026-01-15","assignmentTimezone":"America/New_York","userDateTooltip":"Jan 15, 2026 9:00 AM – 11:00 AM","onsite":{"onsiteType":"string"},"remote":{"remoteType":"string","remoteMeetingLink":"https://example.com","remoteMeetingPlatform":"Virtual link provided","onDemandLink":"https://example.com","onDemandAccessInstructions":"string"},"serviceTypes":{"id":1,"label":"Example label"},"serviceProviders":"string","groupedProvider":"string","status":{"id":1,"label":"Example label"},"statusMethod":"string","assignmentMethod":"string","dontAskMeAgain":"string","parentId":"string","redirectTo":"shifts","confirmedTimeSlots":"string","restrictedActionButtons":[],"missingRates":[],"hasRateMissing":true,"requiresTimeSlotPopup":true,"isCompleted":true,"isPast":true,"showRestrictedWarning":true,"restrictedWarningMessage":"This action is restricted for the assigned provider."}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified assignment does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified assignment does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read shifts:read","x-fido-module":"schedule","x-fido-roles":[],"x-fido-area":"Calendar","x-fido-area-rank":2}},"/v1/schedule/check-provider-availability":{"get":{"tags":["Schedule"],"summary":"Check service provider availability","description":"**Required scope:** `schedule:read`  \n**Roles:** admin, scheduler\n\nRetrieve available and favorite service providers based on filters","operationId":"ext_get_schedule_check_provider_availability","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"startTime","in":"query","description":"Filter whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime.","required":false,"schema":{"type":"string","format":"time","example":"09:00:00"}},{"name":"endTime","in":"query","description":"Filter whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","required":false,"schema":{"type":"string","format":"time","example":"17:00:00"}},{"name":"shiftBlocks","in":"query","description":"Comma-separated shift block IDs (only for type=shift)","required":false,"schema":{"type":"string","example":"1,2,3"}},{"name":"assignmentShiftId","in":"query","description":"Assignment ID (type=assignment) or Shift ID (type=shift) to exclude providers already assigned to it","required":false,"schema":{"type":"string","example":"ASG-XDMSDH"}},{"name":"employmentStatus","in":"query","description":"Employment status filter","required":false,"schema":{"type":"string","example":"staff"}},{"name":"serviceTypes","in":"query","description":"Comma-separated service type IDs","required":false,"schema":{"type":"string","example":"1,2,3"}},{"name":"serviceProviderTypes","in":"query","description":"Comma-separated service provider type IDs","required":false,"schema":{"type":"string","example":"1,2"}},{"name":"locationTypes","in":"query","description":"Comma-separated location types","required":false,"schema":{"type":"string","example":"remote,onsite,hybrid"}},{"name":"skills","in":"query","description":"Comma-separated skill IDs","required":false,"schema":{"type":"string","example":"1,2,3"}},{"name":"specializations","in":"query","description":"Comma-separated specialization IDs","required":false,"schema":{"type":"string","example":"1,2"}},{"name":"certifications","in":"query","description":"Comma-separated certification IDs","required":false,"schema":{"type":"string","example":"1,2,3"}},{"name":"clearances","in":"query","description":"Comma-separated clearance IDs","required":false,"schema":{"type":"string","example":"1,2"}},{"name":"client","in":"query","description":"Client ID for favorite provider filtering","required":false,"schema":{"type":"string","example":"CLT-ABC123"}},{"name":"consumer","in":"query","description":"Consumer ID for favorite provider filtering (only for type=assignment)","required":false,"schema":{"type":"string","example":"USER-XYZ789"}},{"name":"type","in":"query","description":"Type filter (assignment or shift)","required":false,"schema":{"type":"string","enum":["assignment","shift"],"example":"assignment"}}],"responses":{"200":{"description":"Service provider availability retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service provider availability retrieved successfully"},"data":{"properties":{"availableProviders":{"type":"object"},"favoriteProviders":{"type":"object"},"partiallyAvailableProviders":{"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read","x-fido-module":"schedule","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assign and availability","x-fido-area-rank":0}},"/v1/schedule/client-portal/overview":{"get":{"tags":["Schedule"],"summary":"Get client portal schedule overview","description":"**Required scope:** `schedule:read`  \n**Roles:** client\n\nRetrieve schedule overview data for client portal (assignments and shifts combined)","operationId":"ext_get_schedule_client_portal_overview","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"type","in":"query","description":"Type filter (assignment or request)","required":false,"schema":{"type":"string","enum":["assignment","request"],"example":"assignment"}}],"responses":{"200":{"description":"Schedule overview retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Schedule overview retrieved successfully"},"data":{"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read","x-fido-module":"schedule","x-fido-roles":["client"],"x-fido-area":"Overviews","x-fido-area-rank":1}},"/v1/schedule/overview":{"get":{"tags":["Schedule"],"summary":"Get admin schedule overview","description":"**Required scope:** `schedule:read`  \n**Roles:** admin, scheduler\n\nRetrieve schedule overview data for admin panel (assignments or shifts). Without Finance Read `assignmentCostData.totalCost` is null and `assignmentCostData.labelBreakdown` is empty.","operationId":"ext_get_schedule_overview","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"type","in":"query","description":"Type filter (assignment or shift)","required":false,"schema":{"type":"string","enum":["assignment","shift"],"example":"assignment"}},{"name":"startTime","in":"query","description":"Filter whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime.","required":false,"schema":{"type":"string","format":"time","example":"09:00:00"}},{"name":"endTime","in":"query","description":"Filter whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","required":false,"schema":{"type":"string","format":"time","example":"17:00:00"}}],"responses":{"200":{"description":"Schedule overview retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Schedule overview retrieved successfully"},"data":{"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read","x-fido-module":"schedule","x-fido-roles":["admin","scheduler"],"x-fido-area":"Overviews","x-fido-area-rank":1}},"/v1/schedule/provider-portal/overview":{"get":{"tags":["Schedule"],"summary":"Get provider portal schedule overview","description":"**Required scope:** `schedule:read`  \n**Roles:** service-provider\n\nRetrieve schedule overview data for provider portal (assignments and shifts combined)","operationId":"ext_get_schedule_provider_portal_overview","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KC62VCS3"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD format)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}}],"responses":{"200":{"description":"Schedule overview retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Schedule overview retrieved successfully"},"data":{"properties":{"startDate":{"type":"string","example":"2026-01-15","nullable":true},"endDate":{"type":"string","example":"2026-01-15","nullable":true},"assignments":{"properties":{"totalAssignments":{"type":"integer","example":74},"available":{"type":"integer","example":55},"unavailable":{"type":"integer","example":19}},"type":"object"},"serviceLocations":{"properties":{"totalServiceLocations":{"type":"integer","example":100},"remote":{"type":"integer","example":55},"onsite":{"type":"integer","example":20},"hybrid":{"type":"integer","example":25}},"type":"object"},"serviceLocationStats":{"properties":{"total":{"type":"number","example":0},"locations":{"type":"object"}},"type":"object"},"confirmedAssignmentsByServiceType":{"type":"array","items":{"properties":{"category":{"type":"string","example":"ASL"},"filled":{"type":"integer","example":42},"unfilled":{"type":"integer","example":18}},"type":"object"}},"pendingActions":{"properties":{"total":{"type":"number","example":0},"breakdown":{"type":"object"}},"type":"object"},"forecastedEarning":{"properties":{"total":{"type":"number","example":0},"growth":{"type":"string"}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'schedule:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"schedule:read","x-fido-module":"schedule","x-fido-roles":["service-provider"],"x-fido-area":"Overviews","x-fido-area-rank":1}},"/v1/scheduler":{"get":{"tags":["Team"],"summary":"Retrieve scheduler list","description":"**Required scope:** `team:read`  \n**Roles:** admin, scheduler\n\nFetch paginated list of schedulers with search, filters, and sorting","operationId":"ext_get_scheduler","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search by scheduler name or email","required":false,"schema":{"type":"string","example":"scheduler"}},{"name":"status","in":"query","description":"Filter by status ID","required":false,"schema":{"type":"integer","example":1}},{"name":"isPublished","in":"query","description":"Filter by published status","required":false,"schema":{"type":"boolean","example":true}},{"name":"startDate","in":"query","description":"Filter schedulers created after this date","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"Filter schedulers created before this date","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"columns","in":"query","description":"Comma-separated searchable columns","required":false,"schema":{"type":"string","example":"name,email,city"}},{"name":"sortBy","in":"query","description":"Sort field","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Schedulers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"name":{"type":"string","example":"Example name"},"email":{"type":"string","example":"user@example.com","nullable":true},"logo":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"onlineStatus":{"type":"string","example":"online"},"description":{"type":"string","example":"Short human-readable description.","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phone":{"type":"string","example":"+1-555-0142","nullable":true},"phoneExtension":{"type":"string","example":"101","nullable":true},"phoneType":{"type":"string","example":"sms_and_voice","nullable":true},"addressLine1":{"type":"string","example":"123 Main St","nullable":true},"addressLine2":{"type":"string","example":"Suite 200","nullable":true},"city":{"type":"string","example":"Austin","nullable":true},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Alabama"}},"type":"object"},"postalCode":{"type":"string","example":"90210","nullable":true},"videoPhone":{"type":"string","example":"+1-555-0142","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"isPublished":{"type":"boolean","example":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"statusChangedAt":{"description":"When the scheduler entered its current status","type":"string","format":"date-time","example":"2026-06-30 14:29:08","nullable":true},"publishedAt":{"description":"When the scheduler entered its current publication state","type":"string","format":"date-time","example":"2026-06-30 14:29:08","nullable":true},"createdAt":{"type":"string","example":"2026-01-15","nullable":true},"lastLogin":{"type":"string","example":"2026-01-15 09:00:00","nullable":true},"canLogin":{"type":"boolean","example":true},"jobRole":{"type":"string","nullable":true},"role":{"type":"string","example":"example-slug","nullable":true},"requiresPrimaryReassignmentOnDelete":{"type":"boolean","example":true},"otherActiveRoles":{"type":"array","items":[]}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to fetch schedulers."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:read","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-area":"Schedulers","x-fido-area-rank":0},"post":{"tags":["Team"],"summary":"Create a new scheduler","description":"**Required scope:** `team:write`  \n**Roles:** admin, scheduler\n\nCreates a new scheduler","operationId":"ext_post_scheduler","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"An internal staff scheduler. Sent as multipart/form-data when a logo is attached.","required":["name","email","jobRole","status"],"properties":{"name":{"type":"string","maxLength":255,"example":"Jordan Lee"},"email":{"description":"Unique among this organization's users.","type":"string","format":"email","maxLength":255,"example":"jordan@example.test"},"jobRole":{"type":"string","example":"Lead Scheduler"},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"isPublished":{"type":"boolean","example":true,"nullable":true},"role":{"description":"The staff role the user holds: the Scheduler, one of the organization's custom roles (a role with is_custom true) or Admin. Portal roles are refused (422). Only an administrator can send the Admin role (403, code `admin_role_forbidden`). Left out, the user is a Scheduler.","properties":{"id":{"type":"integer","example":7},"label":{"type":"string","example":"Coordinator","nullable":true}},"type":"object","nullable":true},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required unless videoPhone is sent, and when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"phoneExtension":{"type":"string","maxLength":10,"nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gender":{"description":"Required when the scheduler is published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"type":"string","example":"78759","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"notifyOrgWide":{"description":"Receive notifications for every work item in the organization, not only the ones the scheduler owns.","type":"boolean","nullable":true},"defaultTimezone":{"type":"string","example":"America/Chicago","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Scheduler created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Scheduler created successfully"},"data":{"properties":{"id":{"type":"string","example":"USR-ABC123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The email you entered is already in use."},"errors":{"type":"object","example":{"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:write","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-area":"Schedulers","x-fido-area-rank":0}},"/v1/scheduler/export":{"get":{"tags":["Team"],"summary":"Export schedulers to Excel","description":"**Required scope:** `team:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports the Settings → Team scheduler list as an XLSX download. Optionally limited to specific scheduler IDs.","operationId":"ext_get_scheduler_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"query","description":"Scheduler ID(s) to export — single ID or comma-separated list. Omit to export all schedulers.","required":false,"schema":{"type":"string","example":"USR-CGQZDP,USR-ABC123"}}],"responses":{"200":{"description":"XLSX file download","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:read","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Schedulers","x-fido-area-rank":0}},"/v1/scheduler/{scheduler}":{"delete":{"tags":["Team"],"summary":"Delete a scheduler","description":"**Required scope:** `team:delete`  \n**Roles:** admin, scheduler\n\nDeletes a specific scheduler by ID. This will remove the scheduler.","operationId":"ext_delete_scheduler_By_scheduler","parameters":[{"name":"scheduler","in":"path","description":"The ID of the scheduler to delete.","required":true,"schema":{"type":"string","example":"USR-CGQZDP"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Scheduler deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Scheduler deleted successfully!"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure the scheduler ID exists."}},"type":"object"},"example":{"success":false,"message":"Invalid parameters. Ensure the scheduler ID exists."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not Found - Scheduler does not exist","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Scheduler not found."}},"type":"object"},"example":{"success":false,"message":"Scheduler not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:delete","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-area":"Schedulers","x-fido-area-rank":0},"get":{"tags":["Team"],"summary":"Get scheduler details","description":"**Required scope:** `team:read`  \n**Roles:** admin, scheduler\n\nFetch a single scheduler by ID","operationId":"ext_get_scheduler_By_scheduler","parameters":[{"name":"scheduler","in":"path","description":"Scheduler ID","required":true,"schema":{"type":"string","example":"USR-CGQZDP"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Scheduler fetched successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Scheduler fetched successfully."},"data":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"name":{"type":"string","example":"Example name"},"email":{"type":"string","example":"user@example.com","nullable":true},"logo":{"type":"string","format":"url","example":"https://d3t50b2fzyr6w1.cloudfront.net/organization/profile.png"},"onlineStatus":{"type":"string","example":"online"},"description":{"type":"string","example":"Short human-readable description.","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phone":{"type":"string","example":"+1-555-0142","nullable":true},"phoneExtension":{"type":"string","example":"101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice"},"addressLine1":{"type":"string","example":"123 Main St","nullable":true},"addressLine2":{"type":"string","example":"Suite 200","nullable":true},"city":{"type":"string","example":"Austin","nullable":true},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Alabama"}},"type":"object"},"postalCode":{"type":"string","example":"90210","nullable":true},"videoPhone":{"type":"string","example":"+1-555-0142","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"isPublished":{"type":"boolean","example":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"statusChangedAt":{"type":"string","example":"2026-01-15","nullable":true},"publishedAt":{"type":"string","example":"2026-01-15","nullable":true},"createdAt":{"type":"string","example":"2026-01-15","nullable":true},"lastLogin":{"type":"string","example":"2026-01-15 09:00:00","nullable":true},"canLogin":{"type":"boolean","example":true},"jobRole":{"type":"string","nullable":true},"role":{"type":"string","example":"example-slug","nullable":true},"requiresPrimaryReassignmentOnDelete":{"type":"boolean","example":true},"otherActiveRoles":{"type":"array","items":[]}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Scheduler not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Scheduler not found or an error occurred."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:read","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-area":"Schedulers","x-fido-area-rank":0},"post":{"tags":["Team"],"summary":"Update scheduler","description":"**Required scope:** `team:edit`  \n**Roles:** admin, scheduler\n\nUpdates an existing scheduler","operationId":"ext_post_scheduler_By_scheduler","parameters":[{"name":"scheduler","in":"path","description":"Scheduler ID","required":true,"schema":{"type":"string","example":"USR-CGQZDP"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Same fields as create.","properties":{"name":{"type":"string","maxLength":255,"example":"Jordan Lee"},"email":{"description":"Unique among this organization's users.","type":"string","format":"email","maxLength":255,"example":"jordan@example.test"},"jobRole":{"type":"string","example":"Lead Scheduler"},"status":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"isPublished":{"type":"boolean","example":true,"nullable":true},"role":{"description":"The staff role the user holds: the Scheduler, one of the organization's custom roles (a role with is_custom true) or Admin. Portal roles are refused (422), as is changing your own role (an administrator leaving Admin is checked by the administrator guard instead) or the role of a user who is not staff. Only an administrator can send the Admin role or move a user to or from it (403, code `admin_role_forbidden`). Taking Admin from the account owner or the last active administrator is 422 `primary_admin` or `last_admin`; a user who is neither staff nor an administrator, or a staff row that has no login of its own being promoted, is 422 `role_change_unsupported`. Left out, or the role the user already holds, the stored role is kept.","properties":{"id":{"type":"integer","example":7},"label":{"type":"string","example":"Coordinator","nullable":true}},"type":"object","nullable":true},"roles":{"type":"array","items":{"description":"One other role the same person can switch to. Only rows with enabled=true are kept; the list replaces the person's switchable roles. Ignored unless the caller is an admin or scheduler.","properties":{"id":{"description":"Role id. Resolved from slug when omitted.","type":"integer","example":3,"nullable":true},"slug":{"type":"string","example":"consumer"},"enabled":{"type":"boolean","example":true}},"type":"object"},"nullable":true},"description":{"type":"string","maxLength":2000,"minLength":5,"nullable":true},"logo":{"description":"jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"countryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"phone":{"description":"Required unless videoPhone is sent, and when receiveSms is true.","type":"string","maxLength":20,"example":"2025550101","nullable":true},"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"phoneExtension":{"type":"string","maxLength":10,"nullable":true},"videoPhoneCountryCode":{"type":"string","maxLength":5,"example":"+1","nullable":true},"videoPhone":{"type":"string","maxLength":20,"nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gender":{"description":"Required when the scheduler is published.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"type":"string","example":"78759","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"notifyOrgWide":{"description":"Receive notifications for every work item in the organization, not only the ones the scheduler owns.","type":"boolean","nullable":true},"defaultTimezone":{"type":"string","example":"America/Chicago","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Scheduler updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Scheduler updated successfully!"},"data":{"properties":{"id":{"type":"string","example":"USR-CGQZDP"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Scheduler not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Scheduler not found."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:edit","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-area":"Schedulers","x-fido-area-rank":0}},"/v1/service-bodies":{"get":{"tags":["Settings · Service Setup"],"summary":"List all service bodies","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetches all service bodies and returns them in id-label-value format.","operationId":"ext_get_service_bodies","responses":{"200":{"description":"Service Body Fetched Successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Body Fetched Successfully"},"code":{"type":"integer","example":200},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"},"value":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Something went wrong","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Error fetching Service Bodies: SQLSTATE[HY000] [1045] Access denied for user...","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0}},"/v1/service-provider-types":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve all service provider types or filter by tenant ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a list of all service provider types or filter by a specific tenant ID if provided.","operationId":"ext_get_service_provider_types","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"tenantId","in":"query","description":"Tenant ID to filter service provider types.","required":false,"schema":{"type":"string","example":"demotenant"}},{"name":"serviceType","in":"query","description":"Service Type ID to filter service provider types.","required":false,"schema":{"type":"integer","example":4}},{"name":"serviceProviderType","in":"query","description":"Service Provider Type name to filter results.","required":false,"schema":{"type":"string","example":"Testing"}}],"responses":{"200":{"description":"Service Provider Types retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"certifications":{"type":"array","items":{"type":"object"}},"certificationsName":{"type":"array","items":{"type":"object"}},"serviceTypeId":{"type":"integer","example":1},"serviceType":{"type":"string","example":"string"},"isPublished":{"type":"boolean","example":true},"disabledDelete":{"type":"string","example":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"name":"Example name","certifications":[],"certificationsName":[],"serviceTypeId":1,"serviceType":"string","isPublished":true,"disabledDelete":"string"}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":2}}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service provider types","x-fido-area-rank":8},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new service provider type","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new service provider type with a name and optional tenant ID.","operationId":"ext_post_service_provider_types","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"description":"One or more provider types to create.","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Certified Interpreter"}},"type":"object"}},"serviceType":{"description":"The service type the provider types belong to. Required unless customServiceType is sent.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"customServiceType":{"description":"Creates a new service type with this name. Required unless serviceType is sent.","type":"string","example":"Captioning","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Service Provider Type created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Provider Type created!"},"data":{"properties":{"id":{"type":"integer","example":2},"name":{"type":"string","example":"Certified Interpreter"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Service Provider Type created!","data":{"id":2,"name":"Certified Interpreter","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service provider types","x-fido-area-rank":8}},"/v1/service-provider-types/{service_provider_type}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a service provider type","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a service provider type by its ID.","operationId":"ext_delete_service_provider_types_By_service_provider_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"service_provider_type","in":"path","description":"ID of the service provider type to delete.","required":true,"schema":{"type":"integer","example":4}}],"responses":{"200":{"description":"Service Provider Type deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Provider Type deleted!"}},"type":"object"},"example":{"success":true,"message":"Service Provider Type deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service Provider Type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service Provider Type with ID 4 not found."}},"type":"object"},"example":{"success":false,"message":"Service Provider Type with ID 4 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service provider types","x-fido-area-rank":8},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a service provider type by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a specific service provider type by its ID.","operationId":"ext_get_service_provider_types_By_service_provider_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"service_provider_type","in":"path","description":"ID of the service provider type to retrieve.","required":true,"schema":{"type":"integer","example":5}}],"responses":{"200":{"description":"Service Provider Type retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Provider Type retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Service Provider Type retrieved successfully!","data":{"id":1,"name":{"id":1,"label":"Example label"},"serviceType":{"id":1,"label":"Example label"}}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service Provider Type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service Provider Type with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Service Provider Type with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service provider types","x-fido-area-rank":8},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing service provider type","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate a service provider type by ID.","operationId":"ext_put_service_provider_types_By_service_provider_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"service_provider_type","in":"path","description":"ID of the service provider type to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Interpreter"}},"type":"object"}}}},"responses":{"200":{"description":"Service Provider Type updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Provider Type updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Updated Interpreter"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Service Provider Type updated!","data":{"id":3,"name":"Updated Interpreter","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service Provider Type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service Provider Type with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Service Provider Type with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service provider types","x-fido-area-rank":8},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing service provider type","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate a service provider type by ID.","operationId":"ext_patch_service_provider_types_By_service_provider_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"service_provider_type","in":"path","description":"ID of the service provider type to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Interpreter"}},"type":"object"}}}},"responses":{"200":{"description":"Service Provider Type updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Provider Type updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Updated Interpreter"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Service Provider Type updated!","data":{"id":3,"name":"Updated Interpreter","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service Provider Type not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service Provider Type with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Service Provider Type with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service provider types","x-fido-area-rank":8}},"/v1/service-provider/{id}/popup-details":{"get":{"tags":["Providers"],"summary":"Get popup details of a service provider","description":"**Required scope:** `providers:read`\n\nFetches detailed popup information about a service provider including profile, skills, preferences, rates, availability, assignment-specific location type, etc.","operationId":"ext_get_service_provider_By_id_popup_details","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"The unique ID of the service provider (e.g., SPR-JVI5GD)","required":true,"schema":{"type":"string","example":"SPR-JVI5GD"}},{"name":"assignmentId","in":"query","description":"Optional assignment ID to retrieve assignment-specific locationType (e.g., ASG-LVMXVD)","required":false,"schema":{"type":"string","example":"ASG-LVMXVD"}},{"name":"shiftId","in":"query","description":"Optional shift ID to retrieve shift-specific locationType (e.g., SFT-LVMXVD). Mutually exclusive with assignmentId.","required":false,"schema":{"type":"string","example":"SFT-LVMXVD"}},{"name":"isFromPortal","in":"query","description":"Whether this is being requested from a portal (client/consumer/provider) rather than the admin app. Changes the wording of recurring-assignment acceptance status and hides some admin-only fields.","required":false,"schema":{"type":"boolean","example":false}}],"responses":{"200":{"description":"Successful response with service provider details","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Provider details fetched successfully!"},"data":{"properties":{"id":{"type":"string","example":"SPR-JVI5GD"},"name":{"type":"string","example":"John"},"email":{"type":"string","example":"john.doe@example.com"},"countryCode":{"type":"string","example":"+1"},"phone":{"type":"string","example":"9888888888"},"logo":{"type":"string","format":"url","example":"https://fido-devserver.s3.us-east-1.amazonaws.comasas"},"phoneType":{"type":"string","example":"sms_and_voice","nullable":true},"timezone":{"type":"string","example":"US"},"genderPreference":{"type":"string","example":"Male"},"role":{"type":"string","example":"staff"},"status":{"type":"integer","example":1},"locationType":{"type":"string","example":"on-site"},"serviceType":{"type":"string","example":"ASL"},"serviceProviderType":{"type":"string","example":"Deaf"},"isFavorite":{"type":"boolean","example":false},"hearingStatus":{"type":"string","nullable":true},"networkAccess":{"type":"boolean","example":false},"employmentStatus":{"type":"string","nullable":true},"skills":{"type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Advanced"}},"type":"object"}},"certifications":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"NIC"}},"type":"object"}},"clearances":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"HIPPA"}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"}},"availability":{"type":"array","items":{"properties":{"shift_type":{"type":"string","example":"first"},"startDateTime":{"type":"string","format":"date-time","example":"2025-07-30 08:43:31"},"endDateTime":{"type":"string","format":"date-time","example":"2025-07-31 08:43:31"},"bufferBeforeMinutes":{"type":"integer","example":1,"nullable":true},"bufferAfterMinutes":{"type":"integer","example":1,"nullable":true}},"type":"object"}},"rates":{"type":"array","items":{"properties":{"rateType":{"type":"string","example":"Standard"},"rate":{"type":"string","example":"10.00"},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":false},"unit":{"type":"string","example":"hour"},"minimumDuration":{"type":"integer","example":1}},"type":"object"}},"restrictedClients":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLI-123456"},"label":{"type":"string","example":"Client Name"},"image":{"type":"string","format":"url","example":"https://example.com/image.jpg"}},"type":"object"}},"restrictedConsumers":{"type":"array","items":[]},"restrictedServiceProviders":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-N4MTEC"},"label":{"type":"string","example":"John2"},"image":{"type":"string","format":"url","example":"https://fido-devserver.s3.us-east-1.amazonaws.comtest"}},"type":"object"}},"preferredClients":{"type":"array","items":[]},"preferredConsumers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-YJNDSQ"},"label":{"type":"string","example":"demo consumer"},"image":{"type":"string","format":"url","example":"https://fido-devserver.s3.us-east-1.amazonaws.comdemo"}},"type":"object"}},"preferredServiceProviders":{"type":"array","items":[]}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Exception details here","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":[],"x-fido-area":"Providers","x-fido-area-rank":0}},"/v1/service-setup/{tab}":{"get":{"tags":["Settings · Service Setup"],"summary":"Fetch data for a specific service setup tab","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nReturns data for tabs like service_configuration, certifications, clearances, specialization, and skills for the given tenant.","operationId":"ext_get_service_setup_By_tab","parameters":[{"name":"tab","in":"path","description":"Tab name to fetch data for.","required":true,"schema":{"type":"string","enum":["service_configuration","certifications","clearances","specialization","skills"],"example":"service_configuration"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID used to filter results.","required":true,"schema":{"type":"string","example":"abc123"}}],"responses":{"200":{"description":"Service setup data retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Setup details retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"ASL Interpreting"},"isCustom":{"type":"boolean","example":false},"certifications":{"type":"array","items":{"type":"integer","example":3}},"certificationsName":{"type":"array","items":{"type":"string","example":"NIC"}},"serviceProviderType":{"type":"array","items":{"type":"integer","example":1}},"serviceProviderTypeName":{"type":"array","items":{"type":"string","example":"Hearing Interpreter"}}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Service Setup details retrieved!","data":[{"id":1,"name":"ASL Interpreting","isCustom":false,"certifications":[3,4],"certificationsName":["NIC","CDI"],"serviceProviderType":[1,2],"serviceProviderTypeName":["Hearing Interpreter","Deaf Interpreter"]}]}}}},"400":{"description":"Invalid tab name passed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid tab."},"errors":{"type":"string","example":"The selected tab is not supported."}},"type":"object"},"example":{"success":false,"message":"Invalid tab.","errors":"The selected tab is not supported."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service setup view failed: Undefined variable or query issue."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"An unexpected error occurred — please try again.","nullable":true}},"type":"object"},"example":{"success":false,"message":"Service setup view failed: Undefined variable or query issue.","errors":"An unexpected error occurred — please try again."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0}},"/v1/service-types":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve service types with filters","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a list of service types, optionally filtered and paginated. Tenant ID is passed via header.","operationId":"ext_get_service_types","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant filtering.","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Search by name.","required":false,"schema":{"type":"string","example":"medical"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to include in the response.","required":false,"schema":{"type":"string","example":"id,name,isCustom"}},{"name":"sortBy","in":"query","description":"Column to sort by. Defaults to 'name'.","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sort order: asc or desc. Defaults to 'asc'.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of records per page. Defaults to 10.","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Service Types retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Types Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"certifications":{"type":"array","items":[],"nullable":true},"certificationsName":{"type":"array","items":[],"nullable":true},"serviceProviderType":{"type":"string"},"serviceProviderTypeName":{"type":"string","example":"Example name"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new service type","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new service type with a name and optional tenant ID.","operationId":"ext_post_service_types","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","serviceProviderType"],"properties":{"name":{"description":"An existing service type by id, or a new one by label.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"description":"Provider types offered for the service type: existing by id, new by label.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"}}}},"responses":{"201":{"description":"Service Type created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Type created!"},"data":{"properties":{"id":{"type":"integer","example":11},"name":{"type":"string","example":"Deaf Interpreter"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Service Type created!","data":{"id":11,"name":"Deaf Interpreter","isCustom":true}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0}},"/v1/service-types/{service_type}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a service type","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete an existing service type by its ID.","operationId":"ext_delete_service_types_By_service_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"service_type","in":"path","description":"ID of the service type to delete.","required":true,"schema":{"type":"integer","example":4}}],"responses":{"200":{"description":"Service Type deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Type deleted!"}},"type":"object"},"example":{"success":true,"message":"Service Type deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service Type not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service Type with ID 4 not found."}},"type":"object"},"example":{"success":false,"message":"Service Type with ID 4 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error occurred","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a service type by id (always 400)","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\n**Use `/v1/service-setup/{tab}` instead.** This id-only form is registered by the resource route and reaches the same handler, which selects what to return from a `tab` segment this route does not carry, so the call always returns 400 with an invalid-tab error. The path id is never read.","operationId":"ext_get_service_types_By_service_type","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"service_type","in":"path","description":"ID of the service type. Ignored by the handler.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"400":{"description":"Invalid tab — no tab segment is present on this route.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The selected tab is not supported."}},"type":"object"},"example":{"success":false,"message":"The selected tab is not supported."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing service type","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate the name of an existing service type by ID.","operationId":"ext_put_service_types_By_service_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"service_type","in":"path","description":"ID of the service type to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Service"}},"type":"object"}}}},"responses":{"200":{"description":"Service Type updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Type updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Updated Service"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Service Type updated!","data":{"id":3,"name":"Updated Service","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service Type not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service Type with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Service Type with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing service type","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate the name of an existing service type by ID.","operationId":"ext_patch_service_types_By_service_type","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"service_type","in":"path","description":"ID of the service type to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Service"}},"type":"object"}}}},"responses":{"200":{"description":"Service Type updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service Type updated!"},"data":{"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Updated Service"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Service Type updated!","data":{"id":3,"name":"Updated Service","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service Type not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service Type with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Service Type with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service types","x-fido-area-rank":0}},"/v1/set-default-client-location/{id}":{"put":{"tags":["Clients"],"summary":"Set a default client location","description":"**Required scope:** `clients:edit`  \n**Roles:** admin, client, scheduler\n\nSets the specified client location as the default location for the client.","operationId":"ext_put_set_default_client_location_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"The ID of the client location to set as default (e.g. CLTLOC-MBQA3)","required":true,"schema":{"type":"string","example":"CLTLOC-MBQA3"}}],"responses":{"200":{"description":"Default location updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Default location updated successfully"},"data":{"type":"string","example":null,"nullable":true}},"type":"object"}}}},"400":{"description":"Validation or business logic error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Cannot set unpublished location as default."},"data":{"type":"string","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"data":{"type":"string","example":null,"nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:edit","x-fido-module":"clients","x-fido-roles":["admin","client","scheduler"],"x-fido-area":"Locations","x-fido-area-rank":1}},"/v1/set-default-location/{id}":{"put":{"tags":["Settings · Organization Locations"],"summary":"Set a default organization location","description":"**Required scope:** `settings_locations:edit`  \n**Roles:** admin, scheduler\n\nSets the specified organization location as the default location for the organization.","operationId":"ext_put_set_default_location_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"id","in":"path","description":"The ID of the organization location to set as default (e.g. ORGLOC-MBQA3)","required":true,"schema":{"type":"string","example":"ORGLOC-MBQA3"}}],"responses":{"200":{"description":"Default location updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Default location updated successfully"},"data":{"type":"string","example":null,"nullable":true}},"type":"object"}}}},"400":{"description":"Validation or business logic error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Cannot set unpublished location as default."},"data":{"type":"string","example":null,"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_locations:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"data":{"type":"string","example":null,"nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_locations:edit","x-fido-module":"settings_locations","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization locations","x-fido-area-rank":0}},"/v1/settings/assignment-shift-settings":{"get":{"tags":["Settings · Assignments & Shifts"],"summary":"Retrieve specific tab details of assignments and shifts settings","description":"**Required scope:** `settings_assignments_shifts:read`  \n**Roles:** admin, scheduler\n\nFetches the details for a specific tab within the assignments & shifts settings, based on the provided tab identifier.","operationId":"ext_get_settings_assignment_shift_settings","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Assignments and Shifts settings retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"integer","example":1},"enableAssignmentFinanceModule":{"type":"boolean","example":true},"enableShiftFinanceModule":{"type":"boolean","example":true},"enableAssignmentBilling":{"type":"boolean","example":true},"enableAssignmentPayables":{"type":"boolean","example":true},"enableAssignmentReimbursement":{"type":"boolean","example":true},"enableAssignmentRateRules":{"type":"boolean","example":true},"enableShiftBilling":{"type":"boolean","example":true},"enableShiftPayables":{"type":"boolean","example":true},"enableShiftReimbursement":{"type":"boolean","example":true},"enableShiftRateRules":{"type":"boolean","example":true},"enableAssignmentRequests":{"type":"boolean","example":true},"enableShiftRequests":{"type":"boolean","example":true},"primaryMode":{"type":"string","example":"string"},"defaultPriorityLevel":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"allowClientCreateRequest":{"type":"boolean","example":true},"allowPriorityOverrideClient":{"type":"boolean","example":true},"allowConsumerRequestService":{"type":"boolean","example":true},"assignmentDefaultAssignedOwner":{"properties":{"id":{"type":"integer","example":1},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"},"label":{"type":"string","example":"Example label"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"shiftDefaultAssignedOwner":{"properties":{"id":{"type":"integer","example":1},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"},"label":{"type":"string","example":"Example label"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"assignmentsPrimaryAssignmentManager":{"properties":{"id":{"type":"integer","example":1},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"},"label":{"type":"string","example":"Example label"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"shiftsPrimaryAssignmentManager":{"properties":{"id":{"type":"integer","example":1},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"},"label":{"type":"string","example":"Example label"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"allowReassignment":{"type":"boolean","example":true},"fallbackManager":{"properties":{"id":{"type":"integer","example":1},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"onlineStatus":{"type":"string","example":"online"},"label":{"type":"string","example":"Example label"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"reassignmentTriggerResponseTime":{"type":"integer","example":1},"reassignmentTriggerResponseTimeUnit":{"type":"string","example":"string"},"schedulerUnavailable":{"type":"boolean","example":true},"manualReassignmentAdmin":{"type":"boolean","example":true},"requireVerifiedTimeDocumentation":{"type":"boolean","example":true},"useFidoNetwork":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":1,"enableAssignmentFinanceModule":true,"enableShiftFinanceModule":true,"enableAssignmentBilling":true,"enableAssignmentPayables":true,"enableAssignmentReimbursement":true,"enableAssignmentRateRules":true,"enableShiftBilling":true,"enableShiftPayables":true,"enableShiftReimbursement":true,"enableShiftRateRules":true,"enableAssignmentRequests":true,"enableShiftRequests":true,"primaryMode":"string","defaultPriorityLevel":{"id":1,"label":"Example label"},"allowClientCreateRequest":true,"allowPriorityOverrideClient":true,"allowConsumerRequestService":true,"assignmentDefaultAssignedOwner":{"id":1,"image":"https://cdn.example.com/image.png","onlineStatus":"online","label":"Example label","subtitle":"user@example.com"},"shiftDefaultAssignedOwner":{"id":1,"image":"https://cdn.example.com/image.png","onlineStatus":"online","label":"Example label","subtitle":"user@example.com"},"assignmentsPrimaryAssignmentManager":{"id":1,"image":"https://cdn.example.com/image.png","onlineStatus":"online","label":"Example label","subtitle":"user@example.com"},"shiftsPrimaryAssignmentManager":{"id":1,"image":"https://cdn.example.com/image.png","onlineStatus":"online","label":"Example label","subtitle":"user@example.com"},"allowReassignment":true,"fallbackManager":{"id":1,"image":"https://cdn.example.com/image.png","onlineStatus":"online","label":"Example label","subtitle":"user@example.com"},"reassignmentTriggerResponseTime":1,"reassignmentTriggerResponseTimeUnit":"string","schedulerUnavailable":true,"manualReassignmentAdmin":true,"requireVerifiedTimeDocumentation":true,"useFidoNetwork":true}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_assignments_shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_assignments_shifts:read","x-fido-module":"settings_assignments_shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment shift settings","x-fido-area-rank":0},"post":{"tags":["Settings · Assignments & Shifts"],"summary":"Create or update assignments and shifts settings","description":"**Required scope:** `settings_assignments_shifts:edit`  \n**Roles:** admin, scheduler\n\nCreates or updates the assignments and shifts settings for an organization, including core structure and finances","operationId":"ext_post_settings_assignment_shift_settings","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"enableAssignmentFinanceModule":{"type":"boolean","example":true,"nullable":true},"enableShiftFinanceModule":{"type":"boolean","example":true,"nullable":true},"enableAssignmentBilling":{"type":"boolean","example":true,"nullable":true},"enableAssignmentPayables":{"type":"boolean","example":true,"nullable":true},"enableAssignmentReimbursement":{"type":"boolean","example":true,"nullable":true},"enableAssignmentRateRules":{"type":"boolean","example":true,"nullable":true},"enableShiftBilling":{"type":"boolean","example":true,"nullable":true},"enableShiftPayables":{"type":"boolean","example":true,"nullable":true},"enableShiftReimbursement":{"type":"boolean","example":true,"nullable":true},"enableShiftRateRules":{"type":"boolean","example":true,"nullable":true},"enableAssignmentRequests":{"type":"boolean","example":true,"nullable":true},"enableShiftRequests":{"type":"boolean","example":true,"nullable":true},"primaryMode":{"type":"string","example":"assignment","nullable":true},"defaultPriorityLevel":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"allowClientCreateRequest":{"type":"boolean","example":true},"allowPriorityOverrideClient":{"type":"boolean","example":true},"allowConsumerRequestService":{"type":"boolean","example":true},"assignmentDefaultAssignedOwner":{"properties":{"id":{"type":"string","example":"USER-MG7LWN"},"image":{"type":"string","example":""},"label":{"type":"string","example":"Sarah Johnson (Scheduler)"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"shiftDefaultAssignedOwner":{"properties":{"id":{"type":"string","example":"USER-MG7LWN"},"image":{"type":"string","example":""},"label":{"type":"string","example":"Sarah Johnson (Scheduler)"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"assignmentsPrimaryAssignmentManager":{"properties":{"id":{"type":"string","example":"USER-MG7LWN"},"image":{"type":"string","example":""},"label":{"type":"string","example":"Sarah Johnson (Scheduler)"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"shiftsPrimaryAssignmentManager":{"properties":{"id":{"type":"string","example":"USER-MG7LWN"},"image":{"type":"string","example":""},"label":{"type":"string","example":"Sarah Johnson (Scheduler)"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"allowReassignment":{"type":"boolean","example":true},"fallbackManager":{"properties":{"id":{"type":"string","example":"USER-MG7LWN"},"image":{"type":"string","example":""},"label":{"type":"string","example":"Sarah Johnson (Scheduler)"},"subtitle":{"type":"string","example":"user@example.com"}},"type":"object"},"reassignmentTriggerResponseTime":{"type":"integer","example":1},"reassignmentTriggerResponseTimeUnit":{"type":"string","example":"Hour"},"schedulerUnavailable":{"type":"boolean","example":true},"manualReassignmentAdmin":{"type":"boolean","example":true},"requireVerifiedTimeDocumentation":{"type":"boolean","example":true},"useFidoNetwork":{"description":"Use the Fido network (default true): when false, the Handshakes menu is hidden. Omit to keep the stored value.","type":"boolean"}},"type":"object"}}}},"responses":{"200":{"description":"Settings have been updated.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Settings have been updated"},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Settings have been updated","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_assignments_shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_assignments_shifts:edit","x-fido-module":"settings_assignments_shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Assignment shift settings","x-fido-area-rank":0}},"/v1/settings/broadcast-settings":{"get":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Retrieve broadcast & dispatch logic settings","description":"**Required scope:** `settings_broadcast_dispatch:read`  \n**Roles:** admin, scheduler\n\nFetches broadcast & dispatch logic settings","operationId":"ext_get_settings_broadcast_settings","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Broadcast & Dispatch Logic settings retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"integer","example":1},"initialProviderPoolSize":{"type":"integer","example":1},"cycleInterval":{"type":"integer","example":1},"cycleIntervalUnit":{"type":"string","example":"minutes"},"maximumBroadcastRounds":{"type":"integer","example":1},"maximumTotalProvidersContracted":{"type":"integer","example":1},"repeatContactProviderHoursLimit":{"type":"integer","example":1},"autoEscalateAfterFailedRounds":{"type":"integer","example":1},"enableBroadcastDefault":{"type":"boolean","example":true},"enableFidoNetworkBroadcastDefault":{"type":"boolean","example":true},"enableRotationalBroadcast":{"type":"boolean","example":true},"enablePriorityBasedBroadcastBehavior":{"type":"boolean","example":true},"enableRateBaseBehavior":{"type":"boolean","example":true},"userTieredMatchingPools":{"type":"boolean","example":true},"enableProfitabilityBasedMatching":{"type":"boolean","example":true},"expressInterests":{"type":"boolean","example":true},"whoConfirmsAssignments":{"type":"string","example":"string"},"notifySchedulerOnExpressedInterest":{"type":"boolean","example":true},"notifyClientOnExpressedInterest":{"type":"boolean","example":true},"acceptAction":{"type":"boolean","example":true},"whoConfirmsAcceptedAssignments":{"type":"string","example":"string"},"notifySchedulerOnAcceptedAssignments":{"type":"boolean","example":true},"notifyClientOnAcceptedAssignments":{"type":"boolean","example":true},"declineAction":{"type":"boolean","example":true},"declineTimeframe":{"type":"integer","example":1},"declineTimeframeUnit":{"type":"string","example":"string"},"autoFillDelay":{"type":"boolean","example":true},"autoFillDelayTimeframe":{"type":"integer","example":1},"autoFillDelayTimeframeUnit":{"type":"string","example":"string"},"providerResponseWindow":{"type":"boolean","example":true},"providerResponseWindowTimeframe":{"type":"integer","example":1},"providerResponseWindowUnit":{"type":"string","example":"string"},"noProviderResponseNotifyScheduler":{"type":"boolean","example":true},"noProviderResponseNotifySchedulerAfter":{"type":"integer","example":1},"noProviderResponseNotifySchedulerAfterUnit":{"type":"string","example":"string"},"autoEscalateUnfilled":{"type":"boolean","example":true},"autoEscalateUnfilledAfter":{"type":"integer","example":1},"autoEscalateUnfilledAfterUnit":{"type":"string","example":"string"},"notifyUrgentGaps":{"type":"boolean","example":true},"urgentGapsStartIn":{"type":"integer","example":1},"urgentGapsStartInUnit":{"type":"string","example":"string"},"enableEscalationLogic":{"type":"boolean","example":true},"escalateStillUnfilledAfter":{"type":"integer","example":1},"escalateStillUnfilledAfterUnit":{"type":"string","example":"string"},"escalationNotifyMethodEmail":{"type":"boolean","example":true},"escalationNotifyMethodSms":{"type":"boolean","example":true},"escalationNotifyMethodInapp":{"type":"boolean","example":true},"allowManualOverride":{"type":"boolean","example":true},"triggerImmediateRebroadcast":{"type":"boolean","example":true},"notifySchedulerInstantly":{"type":"boolean","example":true},"markAssignmentsAtRisk":{"type":"boolean","example":true},"broadcastPriorityOrder":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"},"order":{"type":"integer","example":1}},"type":"object"},"rotationalBroadcastPrioritizations":{"type":"array","items":{"type":"object"}},"escalationNotifyUsers":{"type":"string","example":"string"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":1,"initialProviderPoolSize":1,"cycleInterval":1,"cycleIntervalUnit":"minutes","maximumBroadcastRounds":1,"maximumTotalProvidersContracted":1,"repeatContactProviderHoursLimit":1,"autoEscalateAfterFailedRounds":1,"enableBroadcastDefault":true,"enableFidoNetworkBroadcastDefault":true,"enableRotationalBroadcast":true,"enablePriorityBasedBroadcastBehavior":true,"enableRateBaseBehavior":true,"userTieredMatchingPools":true,"enableProfitabilityBasedMatching":true,"expressInterests":true,"whoConfirmsAssignments":"string","notifySchedulerOnExpressedInterest":true,"notifyClientOnExpressedInterest":true,"acceptAction":true,"whoConfirmsAcceptedAssignments":"string","notifySchedulerOnAcceptedAssignments":true,"notifyClientOnAcceptedAssignments":true,"declineAction":true,"declineTimeframe":1,"declineTimeframeUnit":"string","autoFillDelay":true,"autoFillDelayTimeframe":1,"autoFillDelayTimeframeUnit":"string","providerResponseWindow":true,"providerResponseWindowTimeframe":1,"providerResponseWindowUnit":"string","noProviderResponseNotifyScheduler":true,"noProviderResponseNotifySchedulerAfter":1,"noProviderResponseNotifySchedulerAfterUnit":"string","autoEscalateUnfilled":true,"autoEscalateUnfilledAfter":1,"autoEscalateUnfilledAfterUnit":"string","notifyUrgentGaps":true,"urgentGapsStartIn":1,"urgentGapsStartInUnit":"string","enableEscalationLogic":true,"escalateStillUnfilledAfter":1,"escalateStillUnfilledAfterUnit":"string","escalationNotifyMethodEmail":true,"escalationNotifyMethodSms":true,"escalationNotifyMethodInapp":true,"allowManualOverride":true,"triggerImmediateRebroadcast":true,"notifySchedulerInstantly":true,"markAssignmentsAtRisk":true,"broadcastPriorityOrder":{"id":"string","label":"Example label","order":1},"rotationalBroadcastPrioritizations":[],"escalationNotifyUsers":"string"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:read","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Broadcast settings","x-fido-area-rank":2},"post":{"tags":["Settings · Broadcast & Dispatch Logic"],"summary":"Create or update broadcast dispatch logic settings","description":"**Required scope:** `settings_broadcast_dispatch:edit`  \n**Roles:** admin, scheduler\n\nCreates or updates the broadcast dispatch logic settings for an organization","operationId":"ext_post_settings_broadcast_settings","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["autoEscalateAfterFailedRounds","cycleInterval","cycleIntervalUnit","initialProviderPoolSize","maximumBroadcastRounds","maximumTotalProvidersContracted","repeatContactProviderHoursLimit"],"properties":{"initialProviderPoolSize":{"type":"integer","example":1},"cycleInterval":{"type":"integer","example":1},"cycleIntervalUnit":{"type":"string","example":"Hours"},"maximumBroadcastRounds":{"type":"integer","example":1},"maximumTotalProvidersContracted":{"type":"integer","example":1},"repeatContactProviderHoursLimit":{"type":"integer","example":1},"autoEscalateAfterFailedRounds":{"type":"integer","example":1},"enableBroadcastDefault":{"type":"boolean","example":true,"nullable":true},"enableFidoNetworkBroadcastDefault":{"type":"boolean","example":true,"nullable":true},"enableRotationalBroadcast":{"type":"boolean","example":true,"nullable":true},"enablePriorityBasedBroadcastBehavior":{"type":"boolean","example":true,"nullable":true},"enableRateBaseBehavior":{"type":"boolean","example":true,"nullable":true},"userTieredMatchingPools":{"type":"boolean","example":true,"nullable":true},"enableProfitabilityBasedMatching":{"type":"boolean","example":true,"nullable":true},"expressInterests":{"type":"boolean","example":true,"nullable":true},"whoConfirmsAssignments":{"type":"string","enum":["manual","auto_confirm"],"example":"manual","nullable":true},"notifySchedulerOnExpressedInterest":{"type":"boolean","example":true,"nullable":true},"notifyClientOnExpressedInterest":{"type":"boolean","example":true,"nullable":true},"acceptAction":{"type":"boolean","example":true,"nullable":true},"whoConfirmsAcceptedAssignments":{"type":"string","enum":["manual","auto_confirm"],"example":"manual","nullable":true},"notifySchedulerOnAcceptedAssignments":{"type":"boolean","example":true,"nullable":true},"notifyClientOnAcceptedAssignments":{"type":"boolean","example":true,"nullable":true},"declineAction":{"type":"boolean","example":true,"nullable":true},"declineTimeframe":{"type":"integer","example":1,"nullable":true},"declineTimeframeUnit":{"type":"string","example":"Minutes","nullable":true},"autoFillDelay":{"type":"boolean","example":true,"nullable":true},"autoFillDelayTimeframe":{"type":"integer","example":1,"nullable":true},"autoFillDelayTimeframeUnit":{"type":"string","example":"Minutes","nullable":true},"noProviderResponseNotifyScheduler":{"type":"boolean","example":true,"nullable":true},"noProviderResponseNotifySchedulerAfter":{"type":"integer","example":1,"nullable":true},"noProviderResponseNotifySchedulerAfterUnit":{"type":"string","example":"Minutes","nullable":true},"autoEscalateUnfilled":{"type":"boolean","example":true,"nullable":true},"autoEscalateUnfilledAfter":{"type":"integer","example":1,"nullable":true},"autoEscalateUnfilledAfterUnit":{"type":"string","example":"Minutes","nullable":true},"notifyUrgentGaps":{"type":"boolean","example":true,"nullable":true},"urgentGapsStartIn":{"type":"integer","example":1,"nullable":true},"urgentGapsStartInUnit":{"type":"string","example":"Hours","nullable":true},"enableEscalationLogic":{"type":"boolean","example":true,"nullable":true},"escalateStillUnfilledAfter":{"type":"integer","example":1,"nullable":true},"escalateStillUnfilledAfterUnit":{"type":"string","example":"Minutes","nullable":true},"escalationNotifyMethodEmail":{"type":"boolean","example":true,"nullable":true},"escalationNotifyMethodSms":{"type":"boolean","example":true,"nullable":true},"escalationNotifyMethodInapp":{"type":"boolean","example":true,"nullable":true},"allowManualOverride":{"type":"boolean","example":true,"nullable":true},"triggerImmediateRebroadcast":{"type":"boolean","example":true,"nullable":true},"notifySchedulerInstantly":{"type":"boolean","example":true,"nullable":true},"markAssignmentsAtRisk":{"type":"boolean","example":true,"nullable":true},"broadcastPriorityOrder":{"description":"The priority order of broadcast dispatch by user type","type":"array","items":{"properties":{"id":{"type":"string","enum":["employee","contractor","agency","network"],"example":"employee"},"label":{"type":"string","example":"Employee"},"order":{"type":"integer","example":1}},"type":"object"},"nullable":true},"rotationalBroadcastPrioritizations":{"description":"Rotational broadcast prioritization strategies","type":"array","items":{"required":["id","label"],"properties":{"id":{"type":"string","enum":["random","skill","rate"],"example":"random"},"label":{"type":"string","example":"Random"}},"type":"object"},"nullable":true},"providerResponseWindow":{"description":"Limit how long a provider has to answer a broadcast.","type":"boolean","example":true,"nullable":true},"providerResponseWindowTimeframe":{"description":"Required when providerResponseWindow is true.","type":"integer","minimum":1,"example":30,"nullable":true},"providerResponseWindowUnit":{"description":"Required when providerResponseWindow is true. A BroadcastInterval unit: seconds, minutes, hours or days, singular or plural.","type":"string","example":"minutes","nullable":true},"escalationNotifyUsers":{"description":"Users notified on escalation, by id.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Settings have been updated.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Settings have been updated"},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Settings have been updated","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_broadcast_dispatch:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_broadcast_dispatch:edit","x-fido-module":"settings_broadcast_dispatch","x-fido-roles":["admin","scheduler"],"x-fido-area":"Broadcast settings","x-fido-area-rank":2}},"/v1/settings/categories-tags":{"get":{"tags":["Settings · General"],"summary":"Retrieve a list of categories and tags","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a list of available categories and tags","operationId":"ext_get_settings_categories_tags","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"tenantId","in":"query","description":"Tenant ID. Used for multi-tenant authentication.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Categories and tags retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"value":1,"label":"Example label","isCustom":true}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":2}}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Categories","x-fido-area-rank":0}},"/v1/settings/communication-configuration":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get all communication configurations","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves all communication configurations with search, filtering, and pagination support","operationId":"ext_get_settings_communication_configuration","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search term to filter configurations by name or value","required":false,"schema":{"type":"string","example":"Shift"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"value":{"type":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Communication configuration","x-fido-area-rank":1},"post":{"tags":["Settings · Notifications & Preferences"],"summary":"Store new communication configurations","description":"**Required scope:** `settings_notifications_preferences:write`  \n**Roles:** admin, scheduler\n\nCreates multiple communication configurations for notification preferences","operationId":"ext_post_settings_communication_configuration","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"description":"Notification preferences configuration with modules and email","required":true,"content":{"application/json":{"schema":{"required":["email","module"],"properties":{"module":{"description":"Array of module configurations","type":"array","items":{"properties":{"id":{"description":"Module identifier","type":"string","example":"assign"},"label":{"description":"Module label/name","type":"string","example":"Assignment"}},"type":"object"}},"email":{"description":"Email address for notifications","type":"string","example":"test@example.com"}},"type":"object"},"example":{"module":[{"id":"assign","label":"Assignment"},{"id":"shift","label":"Shift"}],"email":"test@example.com"}}}},"responses":{"201":{"description":"Successful creation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication configurations created successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The given data was invalid."},"errors":{"properties":{"module":{"type":"array","items":{"type":"string","example":"The module field is required."}},"email":{"type":"array","items":{"type":"string","example":"The email field is required."}},"module.0.label":{"type":"array","items":{"type":"string","example":"The label field is required for each module."}}},"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:write","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Communication configuration","x-fido-area-rank":1}},"/v1/settings/communication-configuration/{communication_configuration}":{"delete":{"tags":["Settings · Notifications & Preferences"],"summary":"Delete communication configuration","description":"**Required scope:** `settings_notifications_preferences:delete`  \n**Roles:** admin, scheduler\n\nDeletes a communication configuration","operationId":"ext_delete_settings_communication_configuration_By_communication_configuration","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"communication_configuration","in":"path","description":"Communication configuration ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Successful deletion","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication configuration deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Communication configuration not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Communication configuration not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:delete","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Communication configuration","x-fido-area-rank":1},"put":{"tags":["Settings · Notifications & Preferences"],"summary":"Update communication configuration","description":"**Required scope:** `settings_notifications_preferences:edit`  \n**Roles:** admin, scheduler\n\nUpdates an existing communication configuration","operationId":"ext_put_settings_communication_configuration_By_communication_configuration","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"communication_configuration","in":"path","description":"Communication configuration ID","required":true,"schema":{"type":"integer","example":1}}],"requestBody":{"description":"Communication configuration data","required":true,"content":{"application/json":{"schema":{"required":["name","value"],"properties":{"name":{"description":"Configuration name","type":"string","example":"Shift"},"value":{"description":"Configuration value","type":"string","example":"test@example.com"}},"type":"object"}}}},"responses":{"200":{"description":"Successful update","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Communication configuration updated successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:edit","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Communication configuration","x-fido-area-rank":1}},"/v1/settings/default-access-setting":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get all default access settings","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves a paginated list of default access settings with search and filtering capabilities","operationId":"ext_get_settings_default_access_setting","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search by role name","required":false,"schema":{"type":"string","example":"Admin"}},{"name":"startDate","in":"query","description":"Filter by start date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2024-01-01"}},{"name":"endDate","in":"query","description":"Filter by end date (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2024-12-31"}},{"name":"sortBy","in":"query","description":"Sort by field","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order (asc/desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"roleId":{"type":"integer","example":1},"role":{"properties":{"id":{"type":"integer","example":2},"name":{"type":"string","example":"Admin"},"slug":{"type":"string","example":"admin"}},"type":"object"},"portalAccess":{"type":"boolean","example":true},"networkEnabled":{"type":"boolean","example":true},"shareWithinOrganization":{"type":"boolean","example":true},"createAssignmentRequest":{"type":"boolean","example":true},"viewManageFinances":{"type":"boolean","example":true},"createAssignment":{"type":"boolean","example":true},"createdAt":{"type":"string","example":"2026-01-15"},"updatedAt":{"type":"string","example":"2026-01-15"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Default access setting","x-fido-area-rank":2}},"/v1/settings/default-access-setting/{id}":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get default access setting by ID","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves a specific default access setting by its ID","operationId":"ext_get_settings_default_access_setting_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"id","in":"path","description":"Default access setting ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Default access setting retrieved successfully."},"data":{"properties":{"id":{"type":"integer","example":1},"roleId":{"type":"integer","example":1},"role":{"properties":{"id":{"type":"integer","example":2},"name":{"type":"string","example":"Admin"},"slug":{"type":"string","example":"admin"}},"type":"object"},"portalAccess":{"type":"boolean","example":true},"networkEnabled":{"type":"boolean","example":true},"shareWithinOrganization":{"type":"boolean","example":true},"createAssignmentRequest":{"type":"boolean","example":true},"viewManageFinances":{"type":"boolean","example":true},"createAssignment":{"type":"boolean","example":true},"createdAt":{"type":"string","example":"2026-01-15"},"updatedAt":{"type":"string","example":"2026-01-15"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Default access setting not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Default access setting not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Default access setting","x-fido-area-rank":2},"put":{"tags":["Settings · Notifications & Preferences"],"summary":"Update default access setting","description":"**Required scope:** `settings_notifications_preferences:edit`  \n**Roles:** admin, scheduler\n\nUpdates a specific default access setting. Supports partial updates - only provided fields will be updated.","operationId":"ext_put_settings_default_access_setting_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"id","in":"path","description":"Default access setting ID","required":true,"schema":{"type":"integer","example":1}}],"requestBody":{"description":"Default access setting data (partial updates supported)","required":true,"content":{"application/json":{"schema":{"properties":{"roleId":{"description":"Role ID (optional)","type":"integer","example":1},"portalAccess":{"description":"Portal access (optional)","type":"boolean","example":true},"networkEnabled":{"description":"Network enabled (optional)","type":"boolean","example":false},"shareWithinOrganization":{"description":"Share within organization (optional)","type":"boolean","example":true},"createAssignmentRequest":{"description":"Create assignment request (optional)","type":"boolean","example":false},"viewManageFinances":{"description":"View manage finances (optional)","type":"boolean","example":true},"createAssignment":{"description":"Create assignment (optional)","type":"boolean","example":false}},"type":"object"}}}},"responses":{"200":{"description":"Successful update","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Default access setting updated successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Default access setting not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Default access setting not found."}},"type":"object"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The given data was invalid."},"errors":{"type":"object","example":{"roleId":["The roleId must be an integer."],"portalAccess":["The portalAccess field must be true or false."],"networkEnabled":["The networkEnabled field must be true or false."],"shareWithinOrganization":["The shareWithinOrganization field must be true or false."],"createAssignmentRequest":["The createAssignmentRequest field must be true or false."],"viewManageFinances":["The viewManageFinances field must be true or false."],"createAssignment":["The createAssignment field must be true or false."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:edit","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Default access setting","x-fido-area-rank":2}},"/v1/settings/delete-requirements/{id}":{"delete":{"tags":["Settings · General"],"summary":"Delete a Requirement and Preference entry","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDeletes a specific requirement and preference record based on the given ID.","operationId":"ext_delete_settings_delete_requirements_By_id","parameters":[{"name":"id","in":"path","description":"ID of the requirement_and_preference to delete","required":true,"schema":{"type":"integer"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID to identify the tenant context","required":true,"schema":{"type":"string","example":"tenant_123"}}],"responses":{"200":{"description":"Requirement and preference deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Requirement and preference deleted successfully."},"data":{"type":"string","example":"Deleted"}},"type":"object"}}}},"400":{"description":"Invalid ID or deletion failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to delete."},"errors":{"type":"string","example":"InvalidArgumentException message"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error occurred.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Server error details","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Requirements and preferences","x-fido-area-rank":10}},"/v1/settings/general-update":{"post":{"tags":["Settings · General"],"summary":"Update an existing organization","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdates an organization's details, including primary location, billing address, skills, certifications, and specializations.","operationId":"ext_post_settings_general_update","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"tenant_123"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Only the fields sent change. Sent as multipart/form-data when a logo, image or document is attached. priority, status, isPublished and isLaunched are rejected here.","required":["name"],"properties":{"phoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"phoneExtension":{"type":"string","maxLength":10,"nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"videoPhone":{"type":"string","nullable":true},"adminCountryCode":{"type":"string","example":"+1","nullable":true},"adminPhone":{"type":"string","nullable":true},"adminPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"nullable":true},"adminPhoneExtension":{"type":"string","nullable":true},"adminVideoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"adminVideoPhone":{"type":"string","nullable":true},"billingStreetAddressLine2":{"type":"string","nullable":true},"taxId":{"type":"string","nullable":true},"industry":{"description":"Required when the organization is published.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"logo":{"type":"string","format":"binary","nullable":true},"publicFacingImage":{"type":"string","format":"binary","nullable":true},"menuLogo":{"type":"string","format":"binary","nullable":true},"loginLogo":{"type":"string","format":"binary","nullable":true},"useDefaultFidoLogo":{"type":"boolean","nullable":true},"showOrganizationName":{"type":"boolean","nullable":true},"platformName":{"type":"string","nullable":true},"tenantUrl":{"type":"string","nullable":true},"supportEmail":{"type":"string","format":"email","nullable":true},"supportPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"supportPhone":{"type":"string","nullable":true},"supportWebsite":{"type":"string","nullable":true},"supportLinkLabel":{"type":"string","nullable":true},"requestServiceFormUrl":{"type":"string","nullable":true},"defaultTimezone":{"description":"Localization.","type":"string","example":"America/Chicago","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization.","type":"string","nullable":true},"startOfWeek":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"startOfDay":{"description":"HH:MM:SS. Required with endOfDay.","type":"string","example":"08:00:00","nullable":true},"endOfDay":{"description":"HH:MM:SS. Required with startOfDay.","type":"string","example":"18:00:00","nullable":true},"officeAvailabilities":{"description":"Weekly office hours.","type":"array","items":{"type":"object"},"nullable":true},"requirementAndPreferences":{"type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"scheduleType":{"description":"Shape of dateTimeSlots for schedule exceptions.","type":"string","enum":["one_time","recurring","multi_day"],"nullable":true},"dateTimeSlots":{"type":"array","items":{"type":"object"},"nullable":true},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"name":{"description":"Name of the organization","type":"string","example":"Demo Tenant"},"website":{"description":"Organization's website URL","type":"string","format":"url","example":"https://www.demotenant.com","nullable":true},"email":{"description":"Organization's contact email","type":"string","format":"email","example":"contact@demotenant.com"},"phone":{"description":"Organization's contact phone number","type":"string","example":"9888888888","nullable":true},"countryCode":{"description":"Organization's contact phone country code","type":"string","example":"+1","nullable":true},"description":{"description":"Brief description of the organization","type":"string","example":"This is a demo tenant for showcasing purposes.","nullable":true},"adminName":{"description":"Name of the organization's administrator","type":"string","example":"Demo Tenant Admin"},"adminEmail":{"description":"Email address of the administrator","type":"string","format":"email","example":"user@example.com"},"addressLine1":{"type":"string","example":"123 Main St."},"addressLine2":{"type":"string","example":"Suite 100","nullable":true},"city":{"type":"string","example":"New York"},"state":{"properties":{"id":{"type":"integer","example":8},"label":{"type":"string","example":"Delaware"}},"type":"object"},"postalCode":{"type":"string","example":"10001"},"billingAddressDifferent":{"type":"boolean","example":true,"nullable":true},"billingStreetAddress":{"type":"string","example":"123 Main St."},"billingCity":{"type":"string","example":"New York"},"billingState":{"description":"Billing state","properties":{"id":{"type":"integer","example":8},"label":{"type":"string","example":"Delaware"}},"type":"object"},"billingPostalCode":{"type":"string","example":"10001"},"domain":{"description":"Custom domain associated with the organization","type":"string","example":"custom.domain.ai","nullable":true},"aRecord":{"description":"A record for DNS settings","type":"string","example":"0.0.0.0","nullable":true},"cnameRecord":{"description":"CNAME record for the organization","type":"string","example":"tenant.demotenant.com","nullable":true},"internalNotes":{"description":"Internal notes for administrators","type":"string","example":"Confidential information regarding tenant.","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Organization updated!","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Organization updated!"},"data":{"properties":{"id":{"type":"string","example":"ORG-U1SZ81"},"name":{"type":"string","example":"Example name"},"tenantId":{"type":"string","example":"TNT-4PS3NV0H"},"website":{"type":"string","example":"string"},"email":{"type":"string","example":"user@example.com"},"adminName":{"type":"string","example":"Example name"},"adminEmail":{"type":"string","example":"user@example.com"},"phone":{"type":"string","example":"+1-555-0142"},"phoneExtension":{"type":"string","example":"101"},"internalNotes":{"type":"string","example":"Added by the scheduler."},"billingAddress":{"type":"array","items":{"type":"object"}}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Organization updated!","data":{"id":"ORG-U1SZ81","name":"Example name","tenantId":"TNT-4PS3NV0H","website":"string","email":"user@example.com","adminName":"Example name","adminEmail":"user@example.com","phone":"+1-555-0142","phoneExtension":"101","internalNotes":"Added by the scheduler.","billingAddress":[]}}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization details","x-fido-area-rank":11}},"/v1/settings/global-event-trigger-notifications":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get all global event trigger notifications","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves all global event trigger notifications","operationId":"ext_get_settings_global_event_trigger_notifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Global event trigger notifications retrieved successfully."},"data":{"type":"object","example":{"deliveryInApp":true,"deliveryEmail":true,"deliverySms":true,"reminderInApp":true,"reminderEmail":true,"reminderSms":true,"summaryTime":"17:30:00","leadInApp":true,"leadEmail":true,"leadSms":true,"leadTime":{"id":"4","label":"4 Hour"},"useSingleEmailAddress":true,"globalEmailAddress":"user@example.com"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Global event trigger notifications","x-fido-area-rank":5},"post":{"tags":["Settings · Notifications & Preferences"],"summary":"Store or update global event trigger notifications","description":"**Required scope:** `settings_notifications_preferences:edit`  \n**Roles:** admin, scheduler\n\nCreates new notifications or updates existing ones","operationId":"ext_post_settings_global_event_trigger_notifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"description":"Global event trigger notification settings","required":true,"content":{"application/json":{"schema":{"properties":{"deliveryInApp":{"description":"Enable in-app notifications for delivery","type":"boolean","example":true,"nullable":true},"deliveryEmail":{"description":"Enable email notifications for delivery","type":"boolean","example":true,"nullable":true},"deliverySms":{"description":"Enable SMS notifications for delivery","type":"boolean","example":true,"nullable":true},"reminderInApp":{"description":"Enable in-app notifications for reminders","type":"boolean","example":true,"nullable":true},"reminderEmail":{"description":"Enable email notifications for reminders","type":"boolean","example":true,"nullable":true},"reminderSms":{"description":"Enable SMS notifications for reminders","type":"boolean","example":true,"nullable":true},"summaryTime":{"description":"Time for daily summary (HH:MM:SS format)","type":"string","example":"17:30:00","nullable":true},"leadInApp":{"description":"Enable in-app notifications for leads","type":"boolean","example":true,"nullable":true},"leadEmail":{"description":"Enable email notifications for leads","type":"boolean","example":true,"nullable":true},"leadSms":{"description":"Enable SMS notifications for leads","type":"boolean","example":true,"nullable":true},"leadTime":{"description":"How long before a work item the reminder goes out, in leadUnit. Between 5 minutes and 7 days. Required when leadInApp or leadEmail is on, or leadSms once SMS is set up.","type":"integer","minimum":1,"example":4,"nullable":true},"leadUnit":{"description":"Required with leadTime.","type":"string","enum":["minutes","hour"],"example":"hour","nullable":true},"dailySummaryEnabled":{"description":"Turns on the daily summary. summaryTime is then required if a reminder channel is on.","type":"boolean","example":true,"nullable":true},"dailySummaryRecipients":{"description":"Required, with at least one item, when dailySummaryEnabled is true.","type":"array","items":{"type":"string","enum":["Client","Service Provider","Consumer","Scheduler"]},"nullable":true},"weeklySummaryEnabled":{"type":"boolean","example":false,"nullable":true},"weeklySummaryTime":{"description":"HH:MM:SS","type":"string","example":"08:00:00","nullable":true},"weeklySummaryDay":{"description":"Required when weeklySummaryEnabled is true.","type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"nullable":true},"weeklySummaryRecipients":{"description":"Required, with at least one item, when weeklySummaryEnabled is true.","type":"array","items":{"type":"string","enum":["Client","Service Provider","Consumer","Scheduler"]},"nullable":true},"useSingleEmailAddress":{"description":"Whether to use a single email address for all communications","type":"boolean","example":true,"nullable":true},"globalEmailAddress":{"description":"Required when useSingleEmailAddress is true.","type":"string","example":"user@example.com"}},"type":"object"},"example":{"deliveryInApp":true,"deliveryEmail":true,"deliverySms":true,"reminderInApp":true,"reminderEmail":true,"reminderSms":true,"summaryTime":"17:30:00","leadInApp":true,"leadEmail":true,"leadSms":true,"leadTime":4,"leadUnit":"hour","dailySummaryEnabled":true,"dailySummaryRecipients":["Scheduler"],"weeklySummaryEnabled":false,"useSingleEmailAddress":true,"globalEmailAddress":"user@example.com"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Configuration updated successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:edit","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Global event trigger notifications","x-fido-area-rank":5}},"/v1/settings/list-requirements":{"get":{"tags":["Settings · General"],"summary":"List the organization's requirements and preferences","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nReturns the organization-level requirement and preference rows — the top tier that client and consumer rows override. See also /v1/requirement-preferences for the flattened lookup lists.","operationId":"ext_get_settings_list_requirements","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"populate","in":"query","description":"When true, every row reports disabledDelete as false — used when seeding a form from these rows rather than editing them in place.","required":false,"schema":{"type":"boolean","example":false}}],"responses":{"200":{"description":"Requirements and preferences retrieved.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Requirement and Preference Retrieved!"},"data":{"properties":{"customizeRequirementPreferences":{"description":"Whether the organization keeps per-service-type rows rather than one default row.","type":"boolean","example":true},"requirementAndPreferences":{"type":"array","items":{"properties":{"id":{"type":"integer","example":5},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"gender":{"properties":{"id":{"type":"string","example":"no_preference","nullable":true},"value":{"type":"string","example":"no_preference","nullable":true},"label":{"type":"string","example":"No Preference","nullable":true}},"type":"object","nullable":true},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"disabledDelete":{"description":"True when the row's provider role is still in use and cannot be removed.","type":"boolean","example":false}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"400":{"description":"Failed to retrieve.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Requirements and preferences","x-fido-area-rank":10}},"/v1/settings/module-event-trigger-notifications":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get all module event trigger notifications","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves a paginated list of module event trigger notifications with search and filtering. Supports fuzzy search on trigger names.","operationId":"ext_get_settings_module_event_trigger_notifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"moduleName","in":"query","description":"Filter by specific module name (e.g., assignments, shifts, requests)","required":false,"schema":{"type":"string","example":"shifts"}},{"name":"search","in":"query","description":"Search query to filter module event trigger notifications by trigger name (supports fuzzy search with spaces and partial matches)","required":false,"schema":{"type":"string","example":"shift created"}},{"name":"sort_by","in":"query","description":"Sort field","required":false,"schema":{"type":"string","example":"module_name"}},{"name":"sort_order","in":"query","description":"Sort order (asc or desc)","required":false,"schema":{"type":"string","example":"asc"}},{"name":"per_page","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Current page number","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"triggerName":{"type":"string","example":"shift_created"},"label":{"type":"string","example":"Shift Created"},"moduleName":{"type":"string","example":"shifts"},"inApp":{"type":"boolean","example":true},"email":{"type":"boolean","example":false},"sms":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":3}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Module event trigger notifications","x-fido-area-rank":3}},"/v1/settings/module-event-trigger-notifications/{module_name}":{"put":{"tags":["Settings · Notifications & Preferences"],"summary":"Update module event trigger notification","description":"**Required scope:** `settings_notifications_preferences:edit`  \n**Roles:** admin, scheduler\n\nUpdates a specific module event trigger notification. Supports partial updates - only provided fields will be updated.","operationId":"ext_put_settings_module_event_trigger_notifications_By_module_name","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"module_name","in":"path","description":"Module name","required":true,"schema":{"type":"string","example":"assignments"}}],"requestBody":{"description":"Module event trigger notification data (partial updates supported)","required":true,"content":{"application/json":{"schema":{"properties":{"triggerName":{"description":"Trigger name (required)","type":"string","example":"assignment_created"},"inApp":{"description":"In-app notification (optional)","type":"boolean","example":false},"email":{"description":"Email notification (optional)","type":"boolean","example":true},"sms":{"description":"SMS notification (optional)","type":"boolean","example":false}},"type":"object"}}}},"responses":{"200":{"description":"Successful update","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Module event trigger notification updated successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Module event trigger notification not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Module event trigger notification not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:edit","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Module event trigger notifications","x-fido-area-rank":3}},"/v1/settings/module-event-trigger-notifications/{trigger_name}":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get module event trigger notification by trigger name","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves a specific trigger notification by its trigger name. Returns only the specific trigger data.","operationId":"ext_get_settings_module_event_trigger_notifications_By_trigger_name","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"trigger_name","in":"path","description":"Trigger name (e.g., assignment_created, shift_updated)","required":true,"schema":{"type":"string","example":"assignment_created"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Module event trigger notification retrieved successfully."},"data":{"properties":{"triggerName":{"type":"string","example":"Example name"},"label":{"type":"string","example":"Example label"},"inApp":{"type":"boolean","example":true},"email":{"type":"boolean","example":true},"sms":{"type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Module event trigger notification not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Module event trigger notification not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Module event trigger notifications","x-fido-area-rank":3}},"/v1/settings/notifications":{"delete":{"tags":["Settings · Notifications & Preferences"],"summary":"Delete multiple notifications","description":"**Required scope:** `settings_notifications_preferences:delete`\n\nDelete multiple notifications for the authenticated user. Tenant-aware if X-Tenant-ID is provided.","operationId":"ext_delete_settings_notifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID (optional, for tenant notifications)","required":false,"schema":{"type":"string","example":"TENANT-123"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["ids"],"properties":{"ids":{"description":"Array of notification IDs to delete","type":"array","items":{"type":"string","example":"NFT-REFTYH"}}},"type":"object"}}}},"responses":{"200":{"description":"Notifications deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notifications deleted successfully"},"deleted_count":{"type":"integer","example":3}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"No notifications found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:delete","x-fido-module":"settings_notifications_preferences","x-fido-roles":[],"x-fido-area":"In-app notifications","x-fido-area-rank":0},"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get all in-app notifications for logged-in user","description":"**Required scope:** `settings_notifications_preferences:read`\n\nRetrieve all in-app notifications for the currently authenticated user with pagination","operationId":"ext_get_settings_notifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. If provided, notifications are fetched from tenant database, else from central database.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Number of notifications to return (without pagination). If not provided, returns with pagination.","required":false,"schema":{"type":"integer","example":5}},{"name":"per_page","in":"query","description":"Number of notifications per page when limit is not used (default: 15)","required":false,"schema":{"type":"integer","example":15}},{"name":"status","in":"query","description":"Filter by read status: all, read, unread","required":false,"schema":{"type":"string","enum":["all","read","unread"],"example":"all"}},{"name":"module","in":"query","description":"Filter by module (e.g., assignment, client, provider)","required":false,"schema":{"type":"string","example":"assignment"}},{"name":"type","in":"query","description":"Filter by notification type (e.g., assignment_created, provider_assigned)","required":false,"schema":{"type":"string","example":"assignment_created"}},{"name":"search","in":"query","description":"Search term to filter notifications","required":false,"schema":{"type":"string","example":"ASG-PTKOK7"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search in (title, message, type, module). If not provided, searches in all columns including assignment_id and assignment_title from meta","required":false,"schema":{"type":"string","example":"title,message"}},{"name":"start_date","in":"query","description":"Filter notifications from this date","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"end_date","in":"query","description":"Filter notifications until this date","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sort_by","in":"query","description":"Sort by field (default: created_at)","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sort_order","in":"query","description":"Sort order (asc or desc, default: desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"time_period","in":"query","description":"Filter by time period","required":false,"schema":{"type":"string","enum":["today","this_week","this_month"],"example":"today"}}],"responses":{"200":{"description":"Notifications retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notifications retrieved successfully"},"data":{"properties":{"notifications":{"type":"array","items":{"properties":{"id":{"type":"string","example":"NOTIF-123"},"title":{"type":"string","example":"New Assignment"},"message":{"type":"string","example":"You have a new assignment"},"created_at":{"type":"string","format":"date-time","example":"2025-12-22T12:00:00Z"}},"type":"object"}},"total":{"type":"integer","example":5},"pagination":{"properties":{"total":{"type":"integer","example":100},"perPage":{"type":"integer","example":15},"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":7}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":[],"x-fido-area":"In-app notifications","x-fido-area-rank":0}},"/v1/settings/notifications/mark-all-as-read":{"post":{"tags":["Settings · Notifications & Preferences"],"summary":"Mark notifications as read","description":"**Required scope:** `settings_notifications_preferences:write`\n\nMark selected notifications or all notifications as read for the logged-in user. If 'ids' are provided, only those will be marked. Otherwise, all notifications will be marked as read.","operationId":"ext_post_settings_notifications_mark_all_as_read","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID","required":false,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Array of notification IDs to mark as read. If omitted, all notifications will be marked.","type":"array","items":{"type":"string","example":"NFT-REFTYH"}}},"type":"object"}}}},"responses":{"200":{"description":"Notifications marked as read successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notifications marked as read successfully"},"data":{"properties":{"updatedCount":{"type":"integer","example":10}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:write","x-fido-module":"settings_notifications_preferences","x-fido-roles":[],"x-fido-area":"In-app notifications","x-fido-area-rank":0}},"/v1/settings/notifications/unread-count":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get unread notifications count","description":"**Required scope:** `settings_notifications_preferences:read`\n\nGet the count of unread notifications for the logged-in user","operationId":"ext_get_settings_notifications_unread_count","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Unread count retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Unread count retrieved successfully"},"data":{"properties":{"unreadCount":{"type":"integer","example":5}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":[],"x-fido-area":"In-app notifications","x-fido-area-rank":0}},"/v1/settings/notifications/{id}/mark-as-read":{"post":{"tags":["Settings · Notifications & Preferences"],"summary":"Mark a notification as read","description":"**Required scope:** `settings_notifications_preferences:write`\n\nMark a specific notification as read","operationId":"ext_post_settings_notifications_By_id_mark_as_read","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","description":"Notification ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Notification marked as read","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notification marked as read"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Notification not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:write","x-fido-module":"settings_notifications_preferences","x-fido-roles":[],"x-fido-area":"In-app notifications","x-fido-area-rank":0}},"/v1/settings/portal/block-list":{"get":{"tags":["Settings · Restricted Users"],"summary":"Retrieve paginated block list with optional filters","description":"**Required scope:** `settings_restricted_users:read`  \n**Roles:** client, consumer, service-provider\n\nFetch a paginated list of block list entries. Allows filtering, searching, and sorting.","operationId":"ext_get_settings_portal_block_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search keyword","schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated list of searchable columns","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Column to sort by","schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Items per page","schema":{"type":"integer"}},{"name":"clientId","in":"query","description":"Filter by client ID","schema":{"type":"string"}},{"name":"consumerId","in":"query","description":"Filter by consumer ID","schema":{"type":"string"}},{"name":"serviceProviderId","in":"query","description":"Filter by service provider ID","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date","example":null}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"blockedUser":{"properties":{"id":{"type":"string","example":"CLT-XXISS8"},"label":{"type":"string","example":"Client2"}},"type":"object"},"blockedUserRoleName":{"type":"string","example":"admin","nullable":true},"blockedUserImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"blockedUserOnlineStatus":{"type":"string","example":"online"},"blockedRole":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Client"},"slug":{"type":"string","example":"client"}},"type":"object"},"notes":{"type":"string","example":"Added by the scheduler.","nullable":true},"blockedDate":{"type":"string","example":"2026-01-15"},"isBehalfOfOrg":{"type":"boolean","example":true},"isBehalfOfRole":{"type":"string","nullable":true},"providerServices":{"type":"array","items":[],"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"object","example":{"search":["Invalid search parameter"]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:read","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Restricted list","x-fido-area-rank":0},"post":{"tags":["Settings · Restricted Users"],"summary":"Create a new block list entry","description":"**Required scope:** `settings_restricted_users:write`  \n**Roles:** client, consumer, service-provider\n\nCreates a new block list record by specifying the user initiating the block and the user being blocked.","operationId":"ext_post_settings_portal_block_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["blockedUser"],"properties":{"blockedUser":{"required":["id","label"],"properties":{"id":{"type":"string","example":"CSM-5W5RVY"},"label":{"type":"string","example":"Consumer"}},"type":"object"},"notes":{"type":"string","example":"Demo","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List created!"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to create."},"errors":{"type":"object","example":{"blockedBy.id":["The blockedBy ID field is required."],"blockedUser.id":["The blockedUser ID field is required."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected server error","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:write","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Restricted list","x-fido-area-rank":0}},"/v1/settings/portal/block-list-export":{"get":{"tags":["Settings · Restricted Users"],"summary":"Export block list to Excel","description":"**Required scope:** `settings_restricted_users:read`  \n**Roles:** client, consumer, service-provider  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports the complete block list to an Excel file for download.","operationId":"ext_get_settings_portal_block_list_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing block list data","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:read","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-rate-limit":"heavy","x-fido-area":"Restricted list","x-fido-area-rank":0}},"/v1/settings/portal/block-list-filter-options":{"get":{"tags":["Settings · Restricted Users"],"summary":"Get block list filter options","description":"**Required scope:** `settings_restricted_users:read`  \n**Roles:** client, consumer, service-provider\n\nReturns categorized filter options (clients, consumers, providers) from the block list.","operationId":"ext_get_settings_portal_block_list_filter_options","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"module","in":"query","description":"The caller's portal role. Picks which groups are filled: `client` returns consumers and providers, `consumer` returns providers, `service-provider` returns all three. Omitted, every group comes back empty.","required":false,"schema":{"type":"string","enum":["client","consumer","service-provider"],"example":"client"}}],"responses":{"200":{"description":"Successfully retrieved filter options","content":{"application/json":{"schema":{"properties":{"clients":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-GGM6R1"},"label":{"type":"string","example":"Client1"},"image":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-RVQLPP/689477ec21a93_Test.jpg"}},"type":"object"}},"consumers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-YWUOOH"},"label":{"type":"string","example":"Consumer1"},"image":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-AZEKLZ/68b97388cabd8_Test.jpg"}},"type":"object"}},"providers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-WHWVON"},"label":{"type":"string","example":"ServiceProvider2"},"image":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg"}},"type":"object"}}},"type":"object"},"example":{"clients":[{"id":"CLT-GGM6R1","label":"Client1","image":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-RVQLPP/689477ec21a93_Test.jpg"}],"consumers":[{"id":"CSM-YWUOOH","label":"Consumer1","image":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-AZEKLZ/68b97388cabd8_Test.jpg"}],"providers":[{"id":"SPR-WHWVON","label":"ServiceProvider2","image":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg"}]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:read","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Restricted list","x-fido-area-rank":0}},"/v1/settings/portal/block-list/{block_list}":{"delete":{"tags":["Settings · Restricted Users"],"summary":"Delete a block list entry","description":"**Required scope:** `settings_restricted_users:delete`  \n**Roles:** client, consumer, service-provider\n\nDeletes a block list entry by its ID. If the ID does not exist, a 404 error will be returned.","operationId":"ext_delete_settings_portal_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"The ID of the block list entry to delete","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List entry deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Block List entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected server error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:delete","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Restricted list","x-fido-area-rank":0},"get":{"tags":["Settings · Restricted Users"],"summary":"Retrieve a single block list entry by ID","description":"**Required scope:** `settings_restricted_users:read`  \n**Roles:** client, consumer, service-provider\n\nReturns details of a specific block list entry including who blocked whom, their roles, profile images, notes, and date.","operationId":"ext_get_settings_portal_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"The ID of the block list entry","required":true,"schema":{"type":"integer","example":5}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Block List entry retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List entry retrieved."},"data":{"properties":{"id":{"type":"integer","example":1},"blockedUser":{"properties":{"id":{"type":"string","example":"CSM-5W5RVY"},"label":{"type":"string","example":"ABC"}},"type":"object"},"blockedUserRoleName":{"type":"string","example":"admin","nullable":true},"blockedRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"blockedUserImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"blockedUserOnlineStatus":{"type":"string","example":"online"},"notes":{"type":"string","example":"Added by the scheduler.","nullable":true},"isBehalfOfOrg":{"type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Block List entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Block List entry not found."},"errors":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:read","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Restricted list","x-fido-area-rank":0},"put":{"tags":["Settings · Restricted Users"],"summary":"Update a block list entry","description":"**Required scope:** `settings_restricted_users:edit`  \n**Roles:** client, consumer, service-provider\n\nPartially update a block list entry. Supports updating the 'blockedBy', 'blockedUser', and 'notes' fields.","operationId":"ext_put_settings_portal_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"ID of the block list entry to update","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"blockedUser":{"properties":{"id":{"description":"ID of the user being blocked","type":"string","example":"CSM-5W5RVY"},"label":{"description":"Label of the user being blocked","type":"string","example":"Consumer"}},"type":"object","nullable":true},"notes":{"description":"Optional notes","type":"string","example":"Updated reason for blocking","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Successfully updated block list entry","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List updated successfully."}},"type":"object"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to update."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Block List entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Blocked user entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Block list update failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:edit","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Restricted list","x-fido-area-rank":0},"patch":{"tags":["Settings · Restricted Users"],"summary":"Update a block list entry","description":"**Required scope:** `settings_restricted_users:edit`  \n**Roles:** client, consumer, service-provider\n\nPartially update a block list entry. Supports updating the 'blockedBy', 'blockedUser', and 'notes' fields.","operationId":"ext_patch_settings_portal_block_list_By_block_list","parameters":[{"name":"block_list","in":"path","description":"ID of the block list entry to update","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"blockedUser":{"properties":{"id":{"description":"ID of the user being blocked","type":"string","example":"CSM-5W5RVY"},"label":{"description":"Label of the user being blocked","type":"string","example":"Consumer"}},"type":"object","nullable":true},"notes":{"description":"Optional notes","type":"string","example":"Updated reason for blocking","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Successfully updated block list entry","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Block List updated successfully."}},"type":"object"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to update."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_restricted_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Block List entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Blocked user entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Block list update failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_restricted_users:edit","x-fido-module":"settings_restricted_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Restricted list","x-fido-area-rank":0}},"/v1/settings/portal/client-portal/location/{id}/rates":{"get":{"tags":["Settings · Rates & Billing"],"summary":"Get paginated client location service rates","description":"**Required scope:** `settings_rates_billing:read`  \n**Roles:** client\n\nReturns a paginated list of service rates configured for a specific client location, including standard and single rates.","operationId":"ext_get_settings_portal_client_portal_location_By_id_rates","parameters":[{"name":"id","in":"path","description":"Client Location ID","required":true,"schema":{"type":"string","example":"LOC-ABCD1234"}},{"name":"search","in":"query","description":"Search term for filtering location rates","required":false,"schema":{"type":"string","example":"ASL"}},{"name":"siteType","in":"query","description":"Filter by site type","required":false,"schema":{"type":"string","example":"onsite"}},{"name":"serviceType","in":"query","description":"Filter by service type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"providerType","in":"query","description":"Filter by service provider type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"serviceRate","in":"query","description":"Filter by rate type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order: asc or desc","required":false,"schema":{"type":"string","example":"desc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number to retrieve","required":false,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant authentication","required":true,"schema":{"type":"string","example":"TNT-OYIHI2I9"}}],"responses":{"200":{"description":"Paginated list of client location service rates","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Standard"}},"type":"object","nullable":true},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Deaf"}},"type":"object","nullable":true},"certification":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"NIC"}},"type":"object","nullable":true},"siteType":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"specialization":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object","nullable":true},"unit":{"type":"string","example":"hour","nullable":true},"rate":{"type":"number","example":0},"minimumDuration":{"type":"integer","example":1,"nullable":true},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true},"disabledDelete":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":25}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The requested location does not belong to the authenticated client. The message is deliberately generic and does not confirm whether the location exists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read","x-fido-module":"settings_rates_billing","x-fido-roles":["client"],"x-fido-area":"Client rates","x-fido-area-rank":5}},"/v1/settings/portal/client-portal/rates":{"get":{"tags":["Settings · Rates & Billing"],"summary":"Get paginated client service rates","description":"**Required scope:** `settings_rates_billing:read`  \n**Roles:** client\n\nReturns a paginated list of client service rates including related service types, rate types, certifications, specializations, etc.","operationId":"ext_get_settings_portal_client_portal_rates","parameters":[{"name":"search","in":"query","description":"Search term for filtering rates","required":false,"schema":{"type":"string","example":"ASL"}},{"name":"siteType","in":"query","description":"Filter by site type","required":false,"schema":{"type":"string","example":"onsite"}},{"name":"serviceType","in":"query","description":"Filter by service type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"providerType","in":"query","description":"Filter by service provider type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"serviceRate","in":"query","description":"Filter by rate type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order: asc or desc","required":false,"schema":{"type":"string","example":"desc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number to retrieve","required":false,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant authentication","required":true,"schema":{"type":"string","example":"TNT-OYIHI2I9"}}],"responses":{"200":{"description":"Paginated list of client service rates","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Standard"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Deaf"}},"type":"object"},"certification":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"NIC"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string"},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"specialization":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"},"unit":{"type":"string","example":"hour","nullable":true},"rate":{"type":"number","example":0},"minimumDuration":{"type":"integer","example":1,"nullable":true},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true},"disabledDelete":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read","x-fido-module":"settings_rates_billing","x-fido-roles":["client"],"x-fido-area":"Client rates","x-fido-area-rank":5}},"/v1/settings/portal/client-portal/requirements":{"get":{"tags":["Settings · General"],"summary":"Get paginated client requirements","description":"**Required scope:** `settings_general:read`  \n**Roles:** client\n\nReturns a paginated list of client requirements with related service types, skills, certifications, etc.","operationId":"ext_get_settings_portal_client_portal_requirements","parameters":[{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order: asc or desc","required":false,"schema":{"type":"string","example":"desc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-OYIHI2I9"}}],"responses":{"200":{"description":"Paginated list of client requirements","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"isDefault":{"type":"boolean","example":true},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Deaf"}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"NIC"}},"type":"object"}},"skill":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Advanced"}},"type":"object"},"clearance":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"HIPPA"}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"}},"gender":{"properties":{"id":{"type":"string","example":"male"},"value":{"type":"string","example":"male"},"label":{"type":"string","example":"Male"}},"type":"object"},"location":{"type":"string","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["client"],"x-fido-area":"Requirements and preferences","x-fido-area-rank":10}},"/v1/settings/portal/client-portal/{tab}":{"get":{"tags":["Settings · General"],"summary":"Get client portal details","description":"**Required scope:** `settings_general:read`  \n**Roles:** client\n\nRetrieves client portal details for the specified tab.","operationId":"ext_get_settings_portal_client_portal_By_tab","parameters":[{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'general', 'localizations','notifications','document_notes','requirement_and_preferences,rates_billing')","required":true,"schema":{"type":"string","enum":["general","localizations"],"example":"general"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-OYIHI2I9"}}],"responses":{"200":{"description":"Client portal details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client Portal details retrieved!"},"data":{"type":"object","oneOf":[{"description":"General tab response","properties":{"name":{"type":"string","example":"Demo Client"},"email":{"type":"string","example":"user@example.com"},"phone":{"type":"string","example":"+1-9876543210"},"portalAccess":{"type":"boolean","example":true}},"type":"object"},{"description":"Localizations tab response","properties":{"language":{"type":"string","example":"en"},"timezone":{"type":"string","example":"America/New_York"},"currency":{"type":"string","example":"USD"}},"type":"object"}]}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error occurred","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["client"],"x-fido-area":"Organization details","x-fido-area-rank":11},"post":{"tags":["Settings · General"],"summary":"Update a client portal","description":"**Required scope:** `settings_general:write`  \n**Roles:** client\n\nUpdates a client portal by auth user for the given payload.","operationId":"ext_post_settings_portal_client_portal_By_tab","parameters":[{"name":"tab","in":"path","description":"The tab to save. `rates_billing` is read-only in the client portal and is refused with a 403.","required":true,"schema":{"type":"string","enum":["details","notification","associated_consumers","requirement_and_preferences","restrictions","rates_billing"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-OYIHI2I9"}}],"requestBody":{"description":"Fields for the tab named in the path; each tab writes only its own fields. On `details` and `notification`, these org-owned keys are refused with a 422 when present at all: status, priority, clientType, portalAccess, isPublished, shiftCapacity, adminFee, adminFeeMethod, adminFeeType, customizeRateBilling, formId, customizeRequirementPreferences, allowClientsToBroadcastImmediately, assignmentRequest. minimumCapacity and maximumCapacity are dropped silently.","required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"`details` tab. Required once the client is published.","type":"string","example":"Demo Client"},"description":{"description":"`details` tab.","type":"string","nullable":true},"email":{"description":"`details` tab. Must be unique among clients.","type":"string","format":"email","example":"client@example.com"},"logo":{"description":"`details` tab. jpg, jpeg, png or gif, max 2 MB.","type":"string","format":"binary","nullable":true},"industry":{"description":"`details` tab. Replaces the client's industries.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"countryCode":{"description":"`details` tab.","type":"string","example":"+1","nullable":true},"phone":{"description":"`details` tab.","type":"string","example":"9876543210","nullable":true},"phoneType":{"description":"`details` tab.","type":"string","example":"voice_only","nullable":true},"phoneExtension":{"description":"`details` tab.","type":"string","example":"204","nullable":true},"videoPhoneCountryCode":{"description":"`details` tab.","type":"string","example":"+1","nullable":true},"videoPhone":{"description":"`details` tab.","type":"string","nullable":true},"gender":{"description":"`details` tab.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"hearingStatus":{"description":"`details` tab.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateOfBirth":{"description":"`details` tab.","type":"string","format":"date","nullable":true},"internalNotes":{"description":"`details` tab.","type":"string","nullable":true},"enableCalendarIntegration":{"description":"`details` tab.","type":"boolean","nullable":true},"locationName":{"description":"`details` tab. Name of the primary location.","type":"string","nullable":true},"addressLine1":{"description":"`details` tab. Primary location. Required once published.","type":"string"},"addressLine2":{"description":"`details` tab. Primary location.","type":"string","nullable":true},"city":{"description":"`details` tab. Primary location. Required once published.","type":"string"},"state":{"description":"`details` tab. Primary location.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"description":"`details` tab. Primary location. Required once published.","type":"string"},"accessInstruction":{"description":"`details` tab. Primary location.","type":"string","nullable":true},"timezone":{"description":"`details` tab. Primary location.","type":"string","example":"America/New_York","nullable":true},"billingAddressDifferent":{"description":"`details` tab. When true, the billing street, city, state and postal code are required.","type":"boolean","nullable":true},"billingStreetAddress":{"description":"`details` tab.","type":"string","nullable":true},"billingStreetAddressLine2":{"description":"`details` tab.","type":"string","nullable":true},"billingCity":{"description":"`details` tab.","type":"string","nullable":true},"billingState":{"description":"`details` tab.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billingPostalCode":{"description":"`details` tab. 12345 or 12345-6789 when billingAddressDifferent is true.","type":"string","example":"19901","nullable":true},"contactName":{"description":"`details` tab. Primary location contact.","type":"string","nullable":true},"contactEmail":{"description":"`details` tab. Primary location contact.","type":"string","format":"email","nullable":true},"role":{"description":"`details` tab. Primary location contact's role.","type":"string","nullable":true},"department":{"description":"`details` tab. Primary location contact.","type":"string","nullable":true},"contactImage":{"description":"`details` tab. Primary location contact photo.","type":"string","format":"binary","nullable":true},"contactPhoneCountryCode":{"description":"`details` tab.","type":"string","example":"+1","nullable":true},"contactPhone":{"description":"`details` tab.","type":"string","nullable":true},"contactPhoneType":{"description":"`details` tab.","type":"string","example":"voice_only","nullable":true},"contactPhoneExtension":{"description":"`details` tab.","type":"string","nullable":true},"contactVideoPhoneCountryCode":{"description":"`details` tab.","type":"string","example":"+1","nullable":true},"contactVideoPhone":{"description":"`details` tab.","type":"string","nullable":true},"documents":{"description":"`details` tab. Saved against the primary location.","type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customFields":{"description":"`details` tab. Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"`details` tab. Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"defaultTimezone":{"description":"`details` tab. Localization.","type":"string","nullable":true},"defaultLanguage":{"description":"`details` tab. Localization.","type":"string","nullable":true},"dateFormat":{"description":"`details` tab. Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"`details` tab. Localization.","type":"string","nullable":true},"startOfWeek":{"description":"`details` tab. Localization.","type":"string","example":"monday","nullable":true},"startOfDay":{"description":"`details` tab. Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"`details` tab. Localization.","type":"string","example":"18:00","nullable":true},"preferredServiceLocations":{"description":"`details` tab. Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentUpdates":{"description":"`notification` tab.","type":"boolean","nullable":true},"serviceReminders":{"description":"`notification` tab.","type":"boolean","nullable":true},"receiveEmail":{"description":"`notification` tab.","type":"boolean","nullable":true},"receiveSms":{"description":"`notification` tab.","type":"boolean","nullable":true},"receiveInApp":{"description":"`notification` tab.","type":"boolean","nullable":true},"profileShareWithinOrganization":{"description":"`notification` tab.","type":"boolean","nullable":true},"associatedConsumer":{"description":"`associated_consumers` tab. Replaces the client's consumer associations.","type":"array","items":{"properties":{"consumer":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"relationship":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"allowPortalAccess":{"type":"boolean","nullable":true},"allowServiceRequests":{"type":"boolean","nullable":true},"allowAssignmentChanges":{"type":"boolean","nullable":true}},"type":"object"},"nullable":true},"requirementAndPreferences":{"description":"`requirement_and_preferences` tab.","type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"customizeRequirementPreferences":{"description":"`requirement_and_preferences` tab only; refused on `details` and `notification`.","type":"boolean","nullable":true},"userRestricted":{"description":"`restrictions` tab.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userPreferred":{"description":"`restrictions` tab.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"description":"`restrictions` tab.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Client portal updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Changes to 'Demo Client' were saved."},"data":{"properties":{"id":{"type":"string","example":"CLT-WJT26R"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The rates_billing tab is read-only in the client portal and managed by the service organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed. Includes any org-owned setting sent by the client (refused when present, even as null or empty). Details tab: status, priority, clientType, portalAccess, isPublished, shiftCapacity, adminFee, adminFeeMethod, adminFeeType, customizeRateBilling, formId, customizeRequirementPreferences. Notifications tab: allowClientsToBroadcastImmediately, assignmentRequest, customizeRequirementPreferences. minimumCapacity and maximumCapacity are ignored rather than refused; the stored values are kept.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"adminFee":["The admin fee is managed by your organization."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error occurred","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["client"],"x-fido-area":"Organization details","x-fido-area-rank":11}},"/v1/settings/portal/client/cancel-request/{id}":{"post":{"tags":["Requests"],"summary":"Cancel request by ID","operationId":"ext_post_settings_portal_client_cancel_request_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the request to cancel","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Request canceled successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request canceled successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The authenticated client is not the billed client on this request — generic message on purpose, so the response can't be used to tell a real id apart from one belonging to another client.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request cancellation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["client"],"description":"**Required scope:** `requests:write`  \n**Roles:** client","x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/consumers":{"get":{"tags":["Clients"],"summary":"Retrieve a list of consumers in client portal","description":"**Required scope:** `clients:read`  \n**Roles:** client\n\nFetches a paginated list of consumers based on filters, search criteria, and sorting options in client portal.","operationId":"ext_get_settings_portal_client_consumers","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search consumers by name, email, or consumer ID.","required":false,"schema":{"type":"string"}},{"name":"serviceTypes","in":"query","description":"Comma-separated list of service type IDs.","required":false,"schema":{"type":"string"}},{"name":"hearingStatus","in":"query","description":"Hearing status filter.","required":false,"schema":{"type":"string"}},{"name":"communicationModes","in":"query","description":"Comma-separated list of communication mode IDs.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by status ID.","required":false,"schema":{"type":"integer"}},{"name":"priority","in":"query","description":"Filter by priority ID.","required":false,"schema":{"type":"integer"}},{"name":"sortBy","in":"query","description":"Field to sort by (e.g., 'user', 'priority', 'created_at').","required":false,"schema":{"type":"string"}},{"name":"startDate","in":"query","description":"Filter consumers created on/after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-08-01"}},{"name":"endDate","in":"query","description":"Filter consumers created on/before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2025-08-21"}},{"name":"sortOrder","in":"query","description":"Sort order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Number of records per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"columns","in":"query","description":"Comma-separated list of columns for filtering or display. Valid columns: user, status, priority, serviceTypes, hearingStatus, communicationModes, associatedClient.","required":false,"schema":{"type":"string","example":"user, status, priority, serviceTypes, hearingStatus, communicationModes, associatedClient"}}],"responses":{"200":{"description":"Consumers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-TUENP2"},"name":{"type":"string","example":"demo consumer 20august-12"},"email":{"type":"string","example":"user@example.com"},"phone":{"type":"string","example":"9888888888"},"logo":{"type":"string","example":"https://fido-devserver.s3.us-east-1.amazonaws.com/consumers/CSM-TUENP2/logo/sample.jpg","nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object"},"associatedClient":{"type":"array","items":{"properties":{"client":{"type":"string","example":"CLT-AJHXRX"},"clientName":{"type":"string","example":"Rate & billing"},"image":{"type":"string","example":null,"nullable":true},"relationship":{"type":"string","example":"Consumer"}},"type":"object"}},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"hearingStatus":{"properties":{"id":{"type":"string","example":"deaf"},"label":{"type":"string","example":"Deaf"}},"type":"object","nullable":true},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL (American Sign Language)"}},"type":"object"}},"portalAccess":{"type":"boolean","example":false,"nullable":true},"isPublished":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":0},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid filters provided. Please check the query parameters."}},"type":"object"}}}},"401":{"description":"Unauthorized - Token missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Consumers in the client portal","x-fido-area-rank":2},"post":{"tags":["Clients"],"summary":"Create a new consumer in client portal","operationId":"ext_post_settings_portal_client_consumers","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for the request","required":true,"schema":{"type":"string","example":"TNT-97MD3QAU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["email","name","portalAccess"],"properties":{"name":{"type":"string","example":"demo consumer 20august-4"},"dateOfBirth":{"description":"Under 18 makes the consumer a minor; a new minor needs a guardian or the independent-minor acknowledgment","type":"string","format":"date","example":"2014-05-01","nullable":true},"hasLegalGuardian":{"description":"Guardians act for this consumer whatever their age. Omit to leave as stored","type":"boolean","nullable":true},"independentMinorAck":{"description":"A minor deliberately with no guardian; needs independentMinorReason","type":"boolean","nullable":true},"independentMinorReason":{"type":"string","maxLength":255,"nullable":true},"notifyMinorToo":{"description":"Under guardianship, the consumer also receives their own notifications","type":"boolean","nullable":true},"guardians":{"description":"Replaces the consumer's guardian links when sent (a JSON string on multipart). Omit to leave them as they are","type":"array","items":{"$ref":"#/components/schemas/GuardianInput"},"nullable":true},"description":{"type":"string","example":"Test description for demo consumer 20august","nullable":true},"logo":{"type":"string","format":"binary","example":null,"nullable":true},"email":{"type":"string","format":"email","example":"user@example.com"},"countryCode":{"type":"string","example":"+1","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"videoPhone":{"type":"string","example":"9888888888","nullable":true},"phone":{"type":"string","example":"9888888888","nullable":true},"phoneType":{"type":"string","enum":["voice_only","sms_and_voice"],"example":"sms_and_voice","nullable":true},"addressLine1":{"type":"string","example":"101 Street"},"addressLine2":{"type":"string","example":"Beagle Run","nullable":true},"city":{"type":"string","example":"Austin"},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Texas"}},"type":"object"},"postalCode":{"type":"string","example":"78759"},"portalAccess":{"type":"boolean","example":false},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"InActive"}},"type":"object"},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"High"}},"type":"object","nullable":true},"hearingStatus":{"properties":{"id":{"type":"string","example":"deaf"},"label":{"type":"string","example":"Deaf"}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Oral"}},"type":"object"}},"preferredServiceLocations":{"type":"array","items":{"properties":{"id":{"type":"string","example":"on_site_only"},"label":{"type":"string","example":"On site only"}},"type":"object"}},"timezone":{"type":"string","example":null,"nullable":true},"defaultTimezone":{"type":"string","example":"America/Juneau"},"startOfWeek":{"type":"string","example":"monday"},"startOfDay":{"type":"string","example":"08:00:00"},"endOfDay":{"type":"string","example":"17:00:00"},"dateFormat":{"type":"array","items":{"properties":{"id":{"type":"string","example":"Y/m/d"},"label":{"type":"string","example":"YYYY/MM/DD"}},"type":"object"}},"timeFormat":{"type":"string","example":"H:i"},"defaultLanguage":{"type":"string","example":null,"nullable":true},"isPublished":{"type":"boolean","example":false,"nullable":true},"internalNotes":{"type":"string","example":"ABCDE","nullable":true},"serviceTypes":{"description":"Default requirement tier. Service types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderTypes":{"description":"Default requirement tier. Provider roles.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"providerTypes":{"description":"Default requirement tier. Provider types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"description":"Default requirement tier. Minimum skill level.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"genderPreferences":{"description":"Default requirement tier. Preferred provider gender.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"certifications":{"description":"Default requirement tier. Required certifications.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"clearances":{"description":"Default requirement tier. Required clearances.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"specializations":{"description":"Default requirement tier. Required specializations.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedClients":{"description":"Clients the consumer may not be scheduled with.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"description":"Consumer users restricted from this consumer.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"clientRestricted":{"description":"Client users restricted from this consumer.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"customizeRequirementPreferences":{"description":"Per-service-type requirements. true reads requirementAndPreferences; false reads the flat default-tier fields.","type":"boolean","nullable":true},"requirementAndPreferences":{"type":"array","items":{"properties":{"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Deaf"}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"CDI"},"isCustom":{"type":"boolean","example":null}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"type":"integer","example":3},"label":{"type":"string","example":"FERPA Training"},"isCustom":{"type":"boolean","example":null}},"type":"object"}},"skill":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Basic"},"isCustom":{"type":"boolean","example":false}},"type":"object"},"gender":{"properties":{"id":{"type":"string","example":"male"},"label":{"type":"string","example":"Male"},"isCustom":{"type":"boolean","example":false}},"type":"object"},"isDefault":{"type":"boolean","example":false}},"type":"object"}},"assignmentUpdates":{"type":"boolean","example":false,"nullable":true},"serviceReminders":{"type":"boolean","example":false},"receiveEmail":{"type":"boolean","example":false,"nullable":true},"receiveSms":{"type":"boolean","example":false,"nullable":true},"receiveInApp":{"type":"boolean","example":false,"nullable":true},"allowServiceRequests":{"type":"boolean","example":false,"nullable":true},"allowAssignmentChanges":{"type":"boolean","example":false,"nullable":true},"allowClientsToBroadcastImmediately":{"description":"Notification preference.","type":"boolean","nullable":true},"allowPortalAccess":{"description":"Lets the consumer use the portal for this client.","type":"boolean","nullable":true},"assignmentRequest":{"description":"Notification preference: assignment requests.","type":"boolean","nullable":true},"consumerType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"phoneExtension":{"description":"Max 10.","type":"string","nullable":true},"userPreferred":{"description":"Users the consumer prefers, by id.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"description":"Users the consumer is restricted from, by id.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"isDuplicated":{"description":"Set when this create duplicates an existing record; records a duplication audit event instead of a plain create","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The record being duplicated. Read only with isDuplicated=true","type":"string","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Consumer created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer created successfully."},"data":{"properties":{"id":{"type":"string","example":"CSM-000123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The given data was invalid."},"errors":{"properties":{"email":{"type":"array","items":{"type":"string","example":"The email field is required."}}},"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Consumer creation failed: [error details]","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:write","x-fido-module":"clients","x-fido-roles":["client"],"description":"**Required scope:** `clients:write`  \n**Roles:** client","x-fido-area":"Consumers in the client portal","x-fido-area-rank":2}},"/v1/settings/portal/client/consumers/guardians/lookup":{"get":{"tags":["Clients"],"summary":"Find an existing guardian by email (own consumers only)","operationId":"ext_get_settings_portal_client_consumers_guardians_lookup","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string"}},{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email"}}],"responses":{"200":{"description":"Lookup result (data is the guardian or null)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string"},"data":{"oneOf":[{"$ref":"#/components/schemas/GuardianLookup"}],"nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"description":"**Required scope:** `clients:read`  \n**Roles:** client","x-fido-area":"Consumers in the client portal","x-fido-area-rank":2}},"/v1/settings/portal/client/consumers/{consumer}":{"delete":{"tags":["Clients"],"summary":"Delete a consumer in client portal","description":"**Required scope:** `clients:delete`  \n**Roles:** client\n\nDeletes a specific consumer by ID in client portal. This will remove the consumer and all associated data such as configurations, preferences, documents, and user links.","operationId":"ext_delete_settings_portal_client_consumers_By_consumer","parameters":[{"name":"consumer","in":"path","description":"The ID of the consumer to delete.","required":true,"schema":{"type":"string","example":"CSM-ABC123"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"responses":{"200":{"description":"Consumer deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer deleted successfully!"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure the consumer ID exists."}},"type":"object"},"example":{"success":false,"message":"Invalid parameters. Ensure the consumer ID exists."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Not Found - Consumer does not exist","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer not found."}},"type":"object"},"example":{"success":false,"message":"Consumer not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:delete","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Consumers in the client portal","x-fido-area-rank":2},"post":{"tags":["Clients"],"summary":"Update an existing consumer in client portal","operationId":"ext_post_settings_portal_client_consumers_By_consumer","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for the request","required":true,"schema":{"type":"string","example":"TNT-97MD3QAU"}},{"name":"consumer","in":"path","description":"Consumer ID to update","required":true,"schema":{"type":"string","example":"CSM-000123"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["requirementAndPreferences"],"properties":{"name":{"type":"string","example":"Updated consumer name"},"dateOfBirth":{"description":"Under 18 makes the consumer a minor; a new minor needs a guardian or the independent-minor acknowledgment","type":"string","format":"date","example":"2014-05-01","nullable":true},"hasLegalGuardian":{"description":"Guardians act for this consumer whatever their age. Omit to leave as stored","type":"boolean","nullable":true},"independentMinorAck":{"description":"A minor deliberately with no guardian; needs independentMinorReason","type":"boolean","nullable":true},"independentMinorReason":{"type":"string","maxLength":255,"nullable":true},"notifyMinorToo":{"description":"Under guardianship, the consumer also receives their own notifications","type":"boolean","nullable":true},"guardians":{"description":"Replaces the consumer's guardian links when sent (a JSON string on multipart). Omit to leave them as they are","type":"array","items":{"$ref":"#/components/schemas/GuardianInput"},"nullable":true},"description":{"type":"string","example":"Updated description","nullable":true},"logo":{"type":"string","format":"binary","example":null,"nullable":true},"email":{"type":"string","format":"email","example":"user@example.com"},"countryCode":{"type":"string","example":"+1","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"videoPhone":{"type":"string","example":"9777777777","nullable":true},"phone":{"type":"string","example":"9666666666","nullable":true},"phoneType":{"type":"string","enum":["voice_only","sms_and_voice"],"example":"voice_only","nullable":true},"addressLine1":{"type":"string","example":"202 Updated Street"},"addressLine2":{"type":"string","example":"Updated Lane","nullable":true},"city":{"type":"string","example":"Dallas"},"state":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Texas"}},"type":"object"},"postalCode":{"type":"string","example":"75201"},"portalAccess":{"type":"boolean","example":true},"status":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Active"}},"type":"object"},"priority":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Medium"}},"type":"object","nullable":true},"hearingStatus":{"properties":{"id":{"type":"string","example":"hard_of_hearing"},"label":{"type":"string","example":"Hard of Hearing"}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"ASL"}},"type":"object"}},"preferredServiceLocations":{"type":"array","items":{"properties":{"id":{"type":"string","example":"remote_only"},"label":{"type":"string","example":"Remote only"}},"type":"object"},"nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"defaultTimezone":{"type":"string","example":"America/New_York"},"startOfWeek":{"type":"string","example":"sunday"},"startOfDay":{"type":"string","example":"09:00:00"},"endOfDay":{"type":"string","example":"18:00:00"},"dateFormat":{"type":"array","items":{"properties":{"id":{"type":"string","example":"d/m/Y"},"label":{"type":"string","example":"DD/MM/YYYY"}},"type":"object"}},"timeFormat":{"type":"string","example":"h:i A"},"defaultLanguage":{"type":"string","example":"en","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"internalNotes":{"type":"string","example":"Updated internal notes","nullable":true},"serviceTypes":{"description":"Default requirement tier. Service types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"serviceProviderTypes":{"description":"Default requirement tier. Provider roles.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"providerTypes":{"description":"Default requirement tier. Provider types.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"skills":{"description":"Default requirement tier. Minimum skill level.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"genderPreferences":{"description":"Default requirement tier. Preferred provider gender.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"certifications":{"description":"Default requirement tier. Required certifications.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"clearances":{"description":"Default requirement tier. Required clearances.","type":"array","items":{"required":["id"],"properties":{"id":{"example":1,"oneOf":[{"type":"integer"},{"type":"string"}]},"file":{"description":"Supporting document.","type":"string","format":"binary","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true}},"type":"object"},"nullable":true},"specializations":{"description":"Default requirement tier. Required specializations.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"restrictedClients":{"description":"Clients the consumer may not be scheduled with.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerRestricted":{"description":"Consumer users restricted from this consumer.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"assignmentRequest":{"description":"Notification preference.","type":"boolean","nullable":true},"allowClientsToBroadcastImmediately":{"description":"The consumer's requests broadcast without scheduler review.","type":"boolean","nullable":true},"customizeRequirementPreferences":{"description":"Per-service-type requirements. true reads requirementAndPreferences; false reads the flat default-tier fields.","type":"boolean","nullable":true},"requirementAndPreferences":{"type":"array","items":{"properties":{"serviceType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"CART"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":4},"label":{"type":"string","example":"Captioner"}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"type":"integer","example":4},"label":{"type":"string","example":"RID"},"isCustom":{"type":"boolean","example":null}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Medical"}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"type":"integer","example":4},"label":{"type":"string","example":"HIPAA Training"},"isCustom":{"type":"boolean","example":null}},"type":"object"}},"skill":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Intermediate"},"isCustom":{"type":"boolean","example":false}},"type":"object"},"gender":{"properties":{"id":{"type":"string","example":"female"},"label":{"type":"string","example":"Female"},"isCustom":{"type":"boolean","example":false}},"type":"object"},"isDefault":{"type":"boolean","example":true}},"type":"object"}},"assignmentUpdates":{"type":"boolean","example":true,"nullable":true},"serviceReminders":{"type":"boolean","example":true},"receiveEmail":{"type":"boolean","example":true,"nullable":true},"receiveSms":{"type":"boolean","example":true,"nullable":true},"receiveInApp":{"type":"boolean","example":true,"nullable":true},"allowServiceRequests":{"type":"boolean","example":true,"nullable":true},"allowAssignmentChanges":{"type":"boolean","example":true,"nullable":true},"allowPortalAccess":{"description":"Lets the consumer use the portal for this client.","type":"boolean","nullable":true},"clientRestricted":{"description":"Clients the consumer is restricted from, by id.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"consumerType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"phoneExtension":{"description":"Max 10.","type":"string","nullable":true},"userPreferred":{"description":"Users the consumer prefers, by id.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"userRestricted":{"description":"Users the consumer is restricted from, by id.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Consumer updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer updated successfully."},"data":{"properties":{"id":{"type":"string","example":"CSM-000123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed. Includes any org-owned consumer setting sent by the client, refused when present, even as null or empty: allowClientsToBroadcastImmediately, assignmentRequest, isSkillOverridden, isCertificationOverridden, isClearanceOverridden, isGenderOverridden, isServiceOverridden, isServiceProviderTypeOverridden, isCommunicationModeOverridden, consumerInternalNotes.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The given data was invalid."},"errors":{"properties":{"email":{"type":"array","items":{"type":"string","example":"The email has already been taken."}}},"type":"object"}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Consumer update failed: [error details]","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:write","x-fido-module":"clients","x-fido-roles":["client"],"description":"**Required scope:** `clients:write`  \n**Roles:** client","x-fido-area":"Consumers in the client portal","x-fido-area-rank":2}},"/v1/settings/portal/client/consumers/{consumer}/tab/{tab}":{"get":{"tags":["Clients"],"summary":"Retrieve specific tab details of a consumer in client portal","description":"**Required scope:** `clients:read`  \n**Roles:** client\n\nFetches the details for a specific tab within a consumer, based on the provided consumer ID and tab identifier in client portal.","operationId":"ext_get_settings_portal_client_consumers_By_consumer_tab_By_tab","parameters":[{"name":"consumer","in":"path","description":"Unique identifier of the consumer","required":true,"schema":{"type":"string","example":"CSM-PMJKT2"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'general', 'requirement_preferences', 'localizations', 'document_notes')","required":true,"schema":{"type":"string","enum":["general","requirement_preferences","localizations","document_notes"],"example":"general"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Consumer details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer details retrieved!"},"data":{"properties":{"id":{"type":"string","example":"CSM-PMJKT2"},"name":{"type":"string","example":"ABCD"},"description":{"type":"string","example":"Test description"},"email":{"type":"string","example":"user@example.com"},"logo":{"type":"string","nullable":true},"countryCode":{"type":"string","example":"+1"},"phone":{"type":"string","example":"9888888888"},"phoneType":{"type":"string","example":"sms_and_voice"},"videoPhoneCountryCode":{"type":"string","example":"+1"},"videoPhone":{"type":"string","example":"9888888888"},"addressLine1":{"type":"string","example":"101 Street"},"addressLine2":{"type":"string","example":"Beagle Run"},"city":{"type":"string","example":"Austin"},"state":{"type":"string","example":"1"},"postalCode":{"type":"string","example":"78759"},"portalAccess":{"type":"boolean","example":false},"assignmentUpdates":{"type":"boolean","example":false},"serviceReminders":{"type":"boolean","example":false},"receiveEmail":{"type":"boolean","example":false},"receiveSms":{"type":"boolean","example":false},"receiveInApp":{"type":"boolean","example":false},"profileShareWithinOrganization":{"type":"boolean","example":false},"isPublished":{"type":"boolean","example":true},"networkAccess":{"type":"boolean","example":false},"status":{"type":"integer","example":1},"priority":{"type":"integer","example":1},"communicationModes":{"type":"array","items":{"type":"integer","example":1}},"hearingStatus":{"type":"string","example":"Deaf"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Consumer details retrieved!","data":{"id":"CSM-PMJKT2","name":"ABCD","description":"Test description","email":"user@example.com","logo":null,"countryCode":"+1","phone":"9888888888","phoneType":"sms_and_voice","videoPhoneCountryCode":"+1","videoPhone":"9888888888","addressLine1":"101 Street","addressLine2":"Beagle Run","city":"Austin","state":"1","postalCode":"78759","portalAccess":false,"assignmentUpdates":false,"serviceReminders":false,"receiveEmail":false,"receiveSms":false,"receiveInApp":false,"profileShareWithinOrganization":false,"isPublished":true,"networkAccess":false,"status":1,"priority":1,"communicationModes":[1,2],"hearingStatus":"Deaf"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified consumer does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified consumer does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Consumers in the client portal","x-fido-area-rank":2}},"/v1/settings/portal/client/export-consumer/{consumer}":{"get":{"tags":["Clients"],"summary":"Export a Consumer in client portal to Excel","description":"**Required scope:** `clients:read`  \n**Roles:** client  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports a single consumer in client portal to an Excel file for download.","operationId":"ext_get_settings_portal_client_export_consumer_By_consumer","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-QLRJVTKH"}},{"name":"consumer","in":"path","description":"Unique identifier of the consumer to export.","required":true,"schema":{"type":"string","example":"CSM-SZ45GS"}}],"responses":{"200":{"description":"CSV file containing all consumers","content":{"text/csv":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Consumer not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Consumer not found with the provided ID."}},"type":"object"},"example":{"success":false,"message":"Consumer not found with the provided ID."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-rate-limit":"heavy","x-fido-area":"Consumers in the client portal","x-fido-area-rank":2}},"/v1/settings/portal/client/export-consumers":{"get":{"tags":["Clients"],"summary":"Export all Consumers in client portal to Excel","description":"**Required scope:** `clients:read`  \n**Roles:** client  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all consumers in client portal to an Excel file for download.","operationId":"ext_get_settings_portal_client_export_consumers","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file containing all consumers","content":{"text/csv":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-rate-limit":"heavy","x-fido-area":"Consumers in the client portal","x-fido-area-rank":2}},"/v1/settings/portal/client/export-locations":{"get":{"tags":["Clients"],"summary":"Export locations to CSV  in client portal","description":"**Required scope:** `clients:read`  \n**Roles:** client  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all client portal locations to an CSV file for download.","operationId":"ext_get_settings_portal_client_export_locations","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-NRLWQEDM"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file containing all location of logged-in client","content":{"text/csv":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-rate-limit":"heavy","x-fido-area":"Locations in the client portal","x-fido-area-rank":3}},"/v1/settings/portal/client/hold-request/{id}":{"post":{"tags":["Requests"],"summary":"Hold request by ID","operationId":"ext_post_settings_portal_client_hold_request_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the request to hold","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Holded request successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Holded request successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The authenticated client is not the billed client on this request — generic message on purpose, so the response can't be used to tell a real id apart from one belonging to another client.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Holding request failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["client"],"description":"**Required scope:** `requests:write`  \n**Roles:** client","x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/location/{id}":{"post":{"tags":["Clients"],"summary":"Update an existing client location in client portal","description":"**Required scope:** `clients:write`  \n**Roles:** client\n\nUpdates a client location in client portal.","operationId":"ext_post_settings_portal_client_location_By_id","parameters":[{"name":"id","in":"path","description":"The ID of the client location to update","required":true,"schema":{"type":"string","example":"CLTLOC-VX6R0"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Acme East Coast Office"},"description":{"type":"string","example":"Primary location for Eastern US operations.","nullable":true},"addressLine1":{"type":"string","example":"456 Industrial Rd"},"addressLine2":{"type":"string","example":"Building B","nullable":true},"city":{"type":"string","example":"Philadelphia"},"state":{"type":"string","example":"PA"},"postalCode":{"type":"string","example":"19103"},"accessInstruction":{"type":"string","example":"Enter through Gate 3. Use intercom for access.","nullable":true},"isPrimaryAddress":{"type":"boolean","example":false},"shiftCapacity":{"type":"boolean","example":true,"nullable":true},"minimumCapacity":{"type":"integer","example":5,"nullable":true},"maximumCapacity":{"type":"integer","example":20,"nullable":true},"timezone":{"type":"string","example":"EST","nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"isPublished":{"type":"boolean","example":false},"department":{"type":"string","example":"Operations"},"contactName":{"type":"string","example":"Jane Doe"},"role":{"type":"string","example":"Operations Manager","nullable":true},"contactEmail":{"type":"string","format":"email","example":"jane.doe@acme.com"},"contactPhone":{"type":"string","example":"+11234567896","nullable":true},"contactPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":6},"label":{"type":"string","example":"example1"}},"type":"object"},"nullable":true},"billingAddressDifferent":{"description":"Bill to the address below instead of the main address.","type":"boolean","example":false,"nullable":true},"billingStreetAddress":{"type":"string","example":"12 Main St","nullable":true},"billingStreetAddressLine2":{"type":"string","example":"Suite 4","nullable":true},"billingCity":{"type":"string","example":"Dover","nullable":true},"billingState":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billingPostalCode":{"type":"string","example":"19901","nullable":true},"contactImage":{"description":"Contact person photo. Send an empty value to remove the current one.","type":"string","format":"binary","nullable":true},"contactPhoneExtension":{"type":"string","example":"204","nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"}},"internalNotes":{"type":"string","example":"Gate code 1234","nullable":true},"logo":{"description":"Image file.","type":"string","format":"binary","nullable":true},"videoPhone":{"type":"string","example":"9888888888","nullable":true},"contactVideoPhone":{"description":"Location contact video phone.","type":"string","nullable":true},"priority":{"description":"Default priority for work at this location.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"countryCode":{"description":"Contact phone country code","type":"string","example":"+1","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Client location updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Location Updated!"},"data":{"properties":{"id":{"type":"integer","example":42}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Location Updated!","data":{"id":42}}}}},"401":{"description":"Unauthorized - Token required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. Includes any org-owned location setting sent by the client, refused when present, even as null or empty: adminFee, adminFeeMethod, adminFeeType, singleRates, rates, client, requireVerifiedTimeDocumentation.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"properties":{"name":{"type":"array","items":{"type":"string","example":"The name field is required."}},"addressLine1":{"type":"array","items":{"type":"string","example":"The address line 1 field is required."}},"city":{"type":"array","items":{"type":"string","example":"The city field is required."}},"status.id":{"type":"array","items":{"type":"string","example":"The status.id field must be an integer."}},"contactEmail":{"type":"array","items":{"type":"string","example":"The contact email must be a valid email address."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation failed","errors":{"name":["The name field is required."],"addressLine1":["The address line 1 field is required."],"city":["The city field is required."],"status.id":["The status.id field must be an integer."],"contactEmail":["The contact email must be a valid email address."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:write","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Locations in the client portal","x-fido-area-rank":3}},"/v1/settings/portal/client/location/{id}/tab/{tab}":{"get":{"tags":["Clients"],"summary":"Retrieve specific tab details of a client location","description":"**Required scope:** `clients:read`  \n**Roles:** client\n\nFetches the details for a specific tab within a client location, based on the provided location ID and tab identifier.","operationId":"ext_get_settings_portal_client_location_By_id_tab_By_tab","parameters":[{"name":"id","in":"path","description":"Unique identifier of the client location","required":true,"schema":{"type":"string","example":"CLTLOC-VX6R0"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'general', 'rates_billing', 'document_notes')","required":true,"schema":{"type":"string","enum":["general","rates_billing","document_notes"],"example":"general"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Client location details retrieved successfully","content":{"application/json":{"schema":{"description":"The payload follows the tab: general, rates_billing and document_notes each return their own object. An unrecognized tab still answers 200, with data null.","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Location details retrieved!"},"data":{"description":"One object for the requested tab. See the example for the general tab.","nullable":true,"oneOf":[{"type":"object"},{"type":"array","items":{"type":"object"}}]}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified client location does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified client location does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Locations in the client portal","x-fido-area-rank":3}},"/v1/settings/portal/client/locations":{"get":{"tags":["Clients"],"summary":"Retrieve a list of client locations","description":"**Required scope:** `clients:read`  \n**Roles:** client\n\nFetches a paginated list of client locations based on filters like search, location, sorting, etc.","operationId":"ext_get_settings_portal_client_locations","parameters":[{"name":"search","in":"query","required":false,"schema":{"description":"Search query to filter locations by name, address, city, etc.","type":"string"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"location","in":"query","required":false,"schema":{"description":"Filter locations by location name.","type":"string"}},{"name":"columns","in":"query","required":false,"schema":{"description":"Search query within visible column content.","type":"string","example":"clientName,address,contact,status"}},{"name":"isPublished","in":"query","description":"Filter clients location by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"status","in":"query","description":"Filter locations by status id (from the statuses lookup table).","required":false,"schema":{"type":"integer","example":1}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter locations created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter locations created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"sortBy","in":"query","required":false,"schema":{"description":"Sort locations by a specific field (e.g., 'name', 'created_at').","type":"string"}},{"name":"sortOrder","in":"query","required":false,"schema":{"description":"Sorting order: ascending ('asc') or descending ('desc').","type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","required":false,"schema":{"description":"Number of locations to retrieve per page.","type":"integer"}}],"responses":{"200":{"description":"Locations retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLTLOC-HQBS7"},"locationName":{"type":"string","example":"Main Office"},"logo":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"addressLine1":{"type":"string","example":"123 Main St","nullable":true},"addressLine2":{"type":"string","example":"Suite 200","nullable":true},"city":{"type":"string","example":"Austin","nullable":true},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"code":{"type":"string"}},"type":"object","nullable":true},"postalCode":{"type":"string","example":"90210","nullable":true},"status":{"type":"integer","example":1,"nullable":true},"statusName":{"type":"string","example":"Active","nullable":true},"isPublished":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true},"isPrimaryAddress":{"type":"boolean","example":true},"department":{"type":"string","example":"Radiology","nullable":true},"contactName":{"type":"string","example":"Jane Smith","nullable":true},"contactImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"contactEmail":{"type":"string","example":"user@example.com","nullable":true},"contactPhone":{"type":"string","example":"+1-555-0142","nullable":true},"contactPhoneExtension":{"type":"string","example":"101","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"client":{"type":"string","example":"CLT-XWB2RY"},"clientName":{"type":"string","example":"Example name","nullable":true},"clientImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"onlineStatus":{"type":"string","example":"online"},"clientEmail":{"type":"string","example":"user@example.com","nullable":true},"clientPhone":{"type":"string","example":"+1-555-0142","nullable":true},"clientType":{"type":"string","example":"Individual","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"},"example":{"success":false,"message":"Invalid parameters. Ensure all required filters are correct."}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:read","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Locations in the client portal","x-fido-area-rank":3},"post":{"tags":["Clients"],"summary":"Create a new location in client portal","description":"**Required scope:** `clients:write`  \n**Roles:** client\n\nCreates a new location in client portal. Rate and billing fields are rejected here (422): adminFee, adminFeeMethod, adminFeeType, enableCustomRates, rates, singleRates, requireVerifiedTimeDocumentation and client are set by the organization, not the portal.","operationId":"ext_post_settings_portal_client_locations","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Acme East Coast Office"},"description":{"type":"string","example":"Primary location for Eastern US operations.","nullable":true},"addressLine1":{"type":"string","example":"456 Industrial Rd"},"addressLine2":{"type":"string","example":"Building B","nullable":true},"city":{"type":"string","example":"Philadelphia"},"state":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Albama"}},"type":"object"},"postalCode":{"type":"string","example":"19103"},"accessInstruction":{"type":"string","example":"Enter through Gate 3. Use intercom for access.","nullable":true},"shiftCapacity":{"type":"boolean","example":true,"nullable":true},"minimumCapacity":{"type":"integer","example":5,"nullable":true},"maximumCapacity":{"type":"integer","example":20,"nullable":true},"timezone":{"type":"string","example":"America/Chicago","nullable":true},"status":{"required":["id","label"],"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Active"}},"type":"object"},"isPublished":{"type":"boolean","example":true,"nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":6},"label":{"type":"string","example":"example1"}},"type":"object"},"nullable":true},"department":{"type":"string","example":"Operations"},"contactName":{"type":"string","example":"Jane Doe"},"role":{"type":"string","example":"Operations Manager","nullable":true},"contactEmail":{"type":"string","format":"email","example":"jane.doe@acme.com"},"countryCode":{"description":"Contact phone country code","type":"string","example":"+1"},"contactPhone":{"description":"Contact phone number","type":"string","example":"9888888888","nullable":true},"contactPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"billingAddressDifferent":{"description":"Bill to the address below instead of the main address.","type":"boolean","example":false,"nullable":true},"billingStreetAddress":{"type":"string","example":"12 Main St","nullable":true},"billingStreetAddressLine2":{"type":"string","example":"Suite 4","nullable":true},"billingCity":{"type":"string","example":"Dover","nullable":true},"billingState":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billingPostalCode":{"type":"string","example":"19901","nullable":true},"contactImage":{"description":"Contact person photo. Send an empty value to remove the current one.","type":"string","format":"binary","nullable":true},"contactPhoneExtension":{"type":"string","example":"204","nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"internalNotes":{"type":"string","example":"Gate code 1234","nullable":true},"logo":{"description":"Image file.","type":"string","format":"binary","nullable":true},"videoPhone":{"type":"string","example":"9888888888","nullable":true},"contactVideoPhone":{"description":"Location contact video phone.","type":"string","nullable":true},"priority":{"description":"Default priority for work at this location.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Location created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Location created successfully"},"data":{"properties":{"id":{"type":"string","example":"LOC-123"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Location created successfully","data":{"id":"LOC-123"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'clients:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. Includes any org-owned location setting sent by the client, refused when present, even as null or empty: adminFee, adminFeeMethod, adminFeeType, singleRates, rates, client, requireVerifiedTimeDocumentation, enableCustomRates.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"properties":{"addressLine1":{"type":"array","items":{"type":"string","example":"The addressLine1 field is required."}},"status":{"type":"array","items":{"type":"string","example":"The status field is required and must include an id."}},"contactEmail":{"type":"array","items":{"type":"string","example":"The contactEmail must be a valid email address."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation failed","errors":{"addressLine1":["The addressLine1 field is required."],"status":["The status field is required and must include an id."],"contactEmail":["The contactEmail must be a valid email address."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"error":{"type":"string","example":"Internal server error."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred — please try again.","error":"Internal server error."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"clients:write","x-fido-module":"clients","x-fido-roles":["client"],"x-fido-area":"Locations in the client portal","x-fido-area-rank":3}},"/v1/settings/portal/client/request/document/files":{"delete":{"tags":["Requests"],"summary":"Delete request files by file IDs","operationId":"ext_delete_settings_portal_client_request_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileIds":{"type":"array","items":{"type":"string"},"example":["FILE-001","FILE-002"]}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"A listed document was not uploaded by the signed-in user, is not on one of their own requests, or does not exist. Nothing is deleted. A successful delete is recorded in the request's History & Logs.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request files deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:delete","x-fido-module":"requests","x-fido-roles":["client"],"description":"**Required scope:** `requests:delete`  \n**Roles:** client","x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/request/{id}/{tab}":{"get":{"tags":["Requests"],"summary":"Retrieve specific tab details of a request","description":"**Required scope:** `requests:read`  \n**Roles:** client\n\nFetches the details for a specific tab within a request, based on the provided request ID and tab identifier.","operationId":"ext_get_settings_portal_client_request_By_id_By_tab","parameters":[{"name":"id","in":"path","description":"Unique identifier of the request","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details','providers','requirementPreferences','documents','sidebar','summary','historyLogs')","required":true,"schema":{"type":"string","enum":["details","requirementPreferences","documents","sidebar","summary","historyLogs"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search the audit log. Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort column (default: created_at). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort direction (default: desc). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Rows per page (default: 10). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number (default: 1). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Request details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"string","example":"ASM-MARH4E"},"title":{"type":"string","example":"Request Title"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":"ASM-MARH4E","title":"Request Title"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified request does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified request does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["client"],"x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/requests":{"get":{"tags":["Requests"],"summary":"Retrieve a list of requests","description":"**Required scope:** `requests:read`  \n**Roles:** client\n\nFetches a paginated list of requests based on search criteria, filters, and sorting options.","operationId":"ext_get_settings_portal_client_requests","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search query to filter request by name, email, or request Id.","required":false,"schema":{"type":"string","example":"request 1"}},{"name":"location","in":"query","description":"Filter request by location ID.","required":false,"schema":{"type":"string","example":"CLTLOC-123"}},{"name":"duration","in":"query","description":"Filter request by duration.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"serviceTypes","in":"query","description":"Filter request by service Types ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"requestedBy","in":"query","description":"Filter request by requester.","required":false,"schema":{"type":"string","example":"consumer"}},{"name":"consumer","in":"query","description":"Filter assignment by consumer ID.","required":false,"schema":{"type":"string","example":"CSM-26TR5"}},{"name":"sortBy","in":"query","description":"Sort clients by a specific field (e.g., 'name', 'created_at').","required":false,"schema":{"type":"string","example":"title"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"columns","in":"query","description":"Search query within visible column content.","required":false,"schema":{"type":"string","example":"title,ID,consumer"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter clients created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter clients created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"startTime","in":"query","description":"Filter requests starting on or after this time (HH:MM).","required":false,"schema":{"type":"string","example":"09:00"}},{"name":"endTime","in":"query","description":"Filter requests ending on or before this time (HH:MM).","required":false,"schema":{"type":"string","example":"17:00"}},{"name":"page","in":"query","description":"Page number to retrieve.","required":false,"schema":{"type":"integer","example":1}},{"name":"perPage","in":"query","description":"Number of records per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"status","in":"query","description":"Filter requests by request-status ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"isPublished","in":"query","description":"Filter requests by their Published status.","required":false,"schema":{"type":"boolean","example":true}},{"name":"customTab","in":"query","description":"Filter requests by tab: 'active', 'archived', 'upcoming', or 'past'.","required":false,"schema":{"type":"string","enum":["active","archived","upcoming","past"],"example":"active"}},{"name":"localSearch","in":"query","description":"The table's own search box: matches only the columns named in `columns`. `search` is the global search.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Requests retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"ASG-XY9EML"},"title":{"type":"string","example":"Example title","nullable":true},"parentTitle":{"type":"string","example":"Example title","nullable":true},"parentId":{"type":"string","nullable":true},"parentScheduleTypeLabel":{"type":"string","example":"Example label","nullable":true},"requestorName":{"type":"string","example":"Example name","nullable":true},"requestorEmail":{"type":"string","example":"user@example.com","nullable":true},"requestorPhone":{"type":"string","example":"+1-555-0142","nullable":true},"requestedVia":{"type":"string","nullable":true},"createdBy":{"type":"string","nullable":true},"assignTo":{"type":"string","nullable":true},"isParent":{"type":"boolean","example":true},"scheduleTypeLabel":{"type":"string","example":"Example label","nullable":true},"scheduleType":{"type":"string","example":"one_time","nullable":true},"duration":{"type":"number","example":0,"nullable":true},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"locationType":{"type":"string","nullable":true},"address":{"properties":{"onsite":{"type":"string"},"remote":{"type":"string"}},"type":"object"},"serviceTypes":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"isPublished":{"type":"boolean","example":true},"consumers":{"type":"array","items":[],"nullable":true},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"groupedConsumer":{"type":"string"},"isPast":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["client"],"x-fido-area":"Client portal","x-fido-area-rank":0},"post":{"tags":["Requests"],"summary":"Create a new request","operationId":"ext_post_settings_portal_client_requests","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["title","description","requestorName","requestorEmail","requestorPhone","requestorCountryCode","assignTo","client","consumer","timezone","scheduleType","dateTimeSlots"],"properties":{"title":{"type":"string","example":"Goodk"},"description":{"type":"string","example":"description of the assignment"},"requestorName":{"type":"string","example":"John Doe"},"requestorEmail":{"type":"string","format":"email","example":"user@example.com"},"requestorPhone":{"type":"string","example":"1234567890"},"requestorCountryCode":{"type":"string","example":"+1"},"requestorPhoneType":{"type":"string","example":"mobile"},"requestorPhoneExtension":{"type":"string","example":"123"},"assignTo":{"description":"The only valid value — a client submitting their own portal request has no 'organization' option.","type":"string","enum":["client"],"example":"client"},"client":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object"},"consumer":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"},"label":{"type":"string","example":"Consumer Name"}},"type":"object"},"timezone":{"type":"string","example":"America/New_York"},"originOfRequest":{"type":"string","example":"client-portal"},"scheduleType":{"type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring"},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly"],"example":"daily"},"scheduleInterval":{"type":"integer","example":2},"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Status Label"}},"type":"object"},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object"},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the assignment"},"submittingBehalfOfSomeone":{"type":"boolean","example":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"}},"allowPartialCoverage":{"description":"Providers may cover part of the time. Defaults to false.","type":"boolean","example":false,"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"description":"A document on an assignment, shift or request.","type":"object","allOf":[{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},{"properties":{"isPublic":{"description":"Visible to the client and consumer, not only to staff.","type":"boolean","example":false,"nullable":true}},"type":"object"}]},"nullable":true},"duration":{"description":"Hours.","type":"number","example":1.5,"nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client and consumer","nullable":true},"isPublished":{"description":"Submit the request. False saves a draft, and relaxes most required fields.","type":"boolean","example":true},"location":{"description":"Where a work item happens. `required` rules follow isPublished; onsite and remote are read by locationType: onsite, remote, or both for hybrid.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"Also accepted at the top level as billingOrganizationLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"Also accepted at the top level as billingClientLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Defaults to primary. Also accepted at the top level as billingOption; the nested value wins if both are sent.","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"description":"Required when onSiteType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"description":"Required when onSiteType=client and newClient is not sent.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"description":"Required when onSiteType=manual. Stored as sent.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"addressLine2":{"type":"string","example":"Suite 4","nullable":true},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"},"accessInstruction":{"type":"string","example":"Use the side entrance","nullable":true}},"type":"object","nullable":true},"manualLocationContact":{"description":"Required when onSiteType=manual.","properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"contactPhoneExtension":{"type":"string","example":"123","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"description":"Required when onSiteType=ondemand.","type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"description":"Required when onDemandLocationType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"description":"Required when onDemandLocationType=client.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"description":"Required when onDemandLocationType=manual.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"onDemandManualLocationContact":{"properties":{"contactName":{"type":"string","example":"Jane Roe","nullable":true},"contactEmail":{"type":"string","format":"email","example":"jane@example.test","nullable":true},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"serviceTypes":{"description":"Required unless serviceTypeBreakdown is sent instead.","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"Per-service-type provider counts — alternative to serviceTypes when provider types are being split per service type.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"virtualMeetingSetup":{"description":"Read by consumer portal requests only.","type":"string","nullable":true},"meetingPlatform":{"description":"Required when remoteType is not ondemand.","type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"multiDay":{"description":"Read when scheduleType=multi_day.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"newConsumer":{"description":"Creates a new consumer inline instead of referencing an existing one.","properties":{"name":{"type":"string","example":"Pat Doe"},"email":{"type":"string","format":"email","example":"pat@example.test","nullable":true},"phone":{"type":"string","example":"1234567890","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phoneExtension":{"type":"string","example":"123","nullable":true},"hearingStatus":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"preferredServiceLocations":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true}},"type":"object"},"oneTime":{"description":"Read when scheduleType=one_time.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"partialDuration":{"description":"Required when allowPartialCoverage is true.","type":"array","items":{"description":"A window a provider may cover on its own. Windows must tile the work item's time exactly.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-01"},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"10:00:00"}},"type":"object"},"nullable":true},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"recurring":{"description":"Read when scheduleType=recurring.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"requirementAndPreferences":{"description":"skillLevel is refused in the client portal.","type":"array","items":{"description":"Requirements and preferences for one service type on a work item. Rows without serviceType.id are skipped; the list replaces what is stored.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderCertifications":{"description":"Provider type, optionally with a certification it must hold. Pairs that do not belong to the service type are skipped.","type":"array","items":{"properties":{"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certifications":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"skillLevel":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"clearances":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"genderPreference":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"signinSignoutRequired":{"description":"Providers must sign in and out. Defaults to false.","type":"boolean","example":false,"nullable":true},"isDuplicated":{"description":"Set when this create duplicates an existing record; records a duplication audit event instead of a plain create","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The record being duplicated. Read only with isDuplicated=true","type":"string","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Request created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request created successfully"},"data":{"properties":{"id":{"type":"string","example":"ASG-001"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request creation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["client"],"description":"**Required scope:** `requests:write`  \n**Roles:** client","x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/requests/export":{"get":{"tags":["Requests"],"summary":"Export All Requests to CSV","description":"**Required scope:** `requests:read`  \n**Roles:** client  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all requests to an CSV file for download.","operationId":"ext_get_settings_portal_client_requests_export","parameters":[{"name":"type","in":"query","description":"Record filter (`all`, `active`, `archived`; default `all`). Also accepted as the output format: `csv` downloads CSV, `xlsx` keeps the default — in which case the record filter falls back to `all`. To use both, keep `type` as the filter and pass `exportType=csv`.","required":false,"schema":{"type":"string","example":"active"}},{"name":"exportType","in":"query","description":"Output format for endpoints where `type` already means something else. On this route `type` is the record filter, so pass the format here: `exportType=csv`. If `type` itself is `csv`/`xlsx` it is read as the format and the record filter falls back to its default.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Type of requests to export. Options: `all` (default), `active`, `archived`.","required":false,"schema":{"type":"string","enum":["all","active","archived"],"example":"active"}}],"responses":{"200":{"description":"CSV file containing requests","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["client"],"x-fido-rate-limit":"heavy","x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/requests/export/{id}":{"get":{"tags":["Requests"],"summary":"Export a Single Request to CSV","description":"**Required scope:** `requests:read`  \n**Roles:** client  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports a single request to an CSV file for download.","operationId":"ext_get_settings_portal_client_requests_export_By_id","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"path","description":"Unique identifier of the request to export.","required":true,"schema":{"type":"string","example":"ASG-45FDX"}}],"responses":{"200":{"description":"CSV file containing request","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["client"],"x-fido-rate-limit":"heavy","x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/requests/{id}":{"post":{"tags":["Requests"],"summary":"Update an existing request","operationId":"ext_post_settings_portal_client_requests_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the request to be updated","required":true,"schema":{"type":"string","example":"ASG-SA2IVL"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["title","description","requestorName","requestorEmail","requestorPhone","requestorCountryCode","assignTo","client","consumer","timezone","scheduleType","dateTimeSlots"],"properties":{"title":{"type":"string","example":"Goodk"},"description":{"type":"string","example":"description of the assignment"},"requestorName":{"type":"string","example":"John Doe"},"requestorEmail":{"type":"string","format":"email","example":"user@example.com"},"requestorPhone":{"type":"string","example":"1234567890"},"requestorCountryCode":{"type":"string","example":"+1"},"requestorPhoneType":{"type":"string","example":"mobile"},"requestorPhoneExtension":{"type":"string","example":"123"},"assignTo":{"description":"Must be client; organization is not accepted.","type":"string","enum":["client"],"example":"client"},"client":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object"},"consumer":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"},"label":{"type":"string","example":"Consumer Name"}},"type":"object"},"timezone":{"type":"string","example":"America/New_York"},"scheduleType":{"type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring"},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly"],"example":"daily"},"scheduleInterval":{"type":"integer","example":2},"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Status Label"}},"type":"object"},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object"},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the assignment"},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"}},"allowPartialCoverage":{"description":"Providers may cover part of the time. Defaults to false.","type":"boolean","example":false,"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"description":"A document on an assignment, shift or request.","type":"object","allOf":[{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},{"properties":{"isPublic":{"description":"Visible to the client and consumer, not only to staff.","type":"boolean","example":false,"nullable":true}},"type":"object"}]},"nullable":true},"duration":{"description":"Hours.","type":"number","example":1.5,"nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client and consumer","nullable":true},"isPublished":{"description":"Submit the request. False saves a draft, and relaxes most required fields.","type":"boolean","example":true},"location":{"description":"Where a work item happens. `required` rules follow isPublished; onsite and remote are read by locationType: onsite, remote, or both for hybrid.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"Also accepted at the top level as billingOrganizationLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"Also accepted at the top level as billingClientLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Defaults to primary. Also accepted at the top level as billingOption; the nested value wins if both are sent.","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"description":"Required when onSiteType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"description":"Required when onSiteType=client and newClient is not sent.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"description":"Required when onSiteType=manual. Stored as sent.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"addressLine2":{"type":"string","example":"Suite 4","nullable":true},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"},"accessInstruction":{"type":"string","example":"Use the side entrance","nullable":true}},"type":"object","nullable":true},"manualLocationContact":{"description":"Required when onSiteType=manual.","properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"contactPhoneExtension":{"type":"string","example":"123","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"description":"Required when onSiteType=ondemand.","type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"description":"Required when onDemandLocationType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"description":"Required when onDemandLocationType=client.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"description":"Required when onDemandLocationType=manual.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"onDemandManualLocationContact":{"properties":{"contactName":{"type":"string","example":"Jane Roe","nullable":true},"contactEmail":{"type":"string","format":"email","example":"jane@example.test","nullable":true},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"serviceTypes":{"description":"Required unless serviceTypeBreakdown is sent instead.","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"Per-service-type provider counts — alternative to serviceTypes when provider types are being split per service type.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"virtualMeetingSetup":{"description":"Read by consumer portal requests only.","type":"string","nullable":true},"meetingPlatform":{"description":"Required when remoteType is not ondemand.","type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"multiDay":{"description":"Read when scheduleType=multi_day.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"newConsumer":{"description":"Creates a new consumer inline instead of referencing an existing one.","properties":{"name":{"type":"string","example":"Pat Doe"},"email":{"type":"string","format":"email","example":"pat@example.test","nullable":true},"phone":{"type":"string","example":"1234567890","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phoneExtension":{"type":"string","example":"123","nullable":true},"hearingStatus":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"preferredServiceLocations":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true}},"type":"object"},"oneTime":{"description":"Read when scheduleType=one_time.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"recurring":{"description":"Read when scheduleType=recurring.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"requirementAndPreferences":{"type":"array","items":{"description":"Requirements and preferences for one service type on a work item. Rows without serviceType.id are skipped; the list replaces what is stored.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderCertifications":{"description":"Provider type, optionally with a certification it must hold. Pairs that do not belong to the service type are skipped.","type":"array","items":{"properties":{"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certifications":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"skillLevel":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"clearances":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"genderPreference":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"submittingBehalfOfSomeone":{"description":"The requestor* fields describe someone other than the caller.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Request updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request created successfully"},"data":{"properties":{"id":{"type":"string","example":"ASG-SA2IVL"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request updation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["client"],"description":"**Required scope:** `requests:write`  \n**Roles:** client","x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/client/requests/{request}":{"delete":{"tags":["Requests"],"summary":"Delete a request","description":"**Required scope:** `requests:delete`  \n**Roles:** client\n\nDeletes a requestt by ID for the given tenant, including child requests and associated files from S3.","operationId":"ext_delete_settings_portal_client_requests_By_request","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"request","in":"path","description":"ID of the request to delete","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Request deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Request not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Request not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:delete","x-fido-module":"requests","x-fido-roles":["client"],"x-fido-area":"Client portal","x-fido-area-rank":0}},"/v1/settings/portal/consumer":{"post":{"tags":["Consumers"],"summary":"Update consumer portal","description":"**Required scope:** `consumers:write`  \n**Roles:** consumer\n\nUpdates a consumer portal by auth user the given payload.","operationId":"ext_post_settings_portal_consumer","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"description":"The consumer's own profile. Org-owned settings are refused, see the 422 response.","required":true,"content":{"application/json":{"schema":{"required":["email","name"],"properties":{"name":{"type":"string","example":"John"},"email":{"type":"string","format":"email","example":"user@example.com"},"description":{"type":"string","nullable":true},"logo":{"description":"Profile image. Send an empty value to remove the current one.","type":"string","format":"binary","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phone":{"type":"string","example":"2025550101","nullable":true},"phoneType":{"type":"string","example":"sms_and_voice","nullable":true},"phoneExtension":{"type":"string","example":"204","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true},"videoPhone":{"type":"string","nullable":true},"videoPhoneType":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"postalCode":{"type":"string","nullable":true},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateOfBirth":{"type":"string","format":"date","nullable":true},"hearingStatus":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"communicationModes":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"internalNotes":{"description":"The consumer's own notes, saved as consumerInternalNotes.","type":"string","nullable":true},"enableCalendarIntegration":{"type":"boolean","nullable":true},"networkAccess":{"description":"Share the consumer's profile with the Fido network.","type":"boolean","nullable":true},"customizeRequirementPreferences":{"type":"boolean","nullable":true},"requirementAndPreferences":{"type":"array","items":{"description":"One service-type requirement and preference row. Rows not sent are deleted.","properties":{"id":{"type":"integer","example":5,"nullable":true},"isDefault":{"type":"boolean","example":false},"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"skill":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"gender":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certification":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"clearance":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specialization":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},"nullable":true},"defaultTimezone":{"description":"Localization.","type":"string","nullable":true},"defaultLanguage":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"dateFormat":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"timeFormat":{"description":"Localization.","type":"string","nullable":true},"startOfWeek":{"description":"Localization.","type":"string","example":"monday","nullable":true},"startOfDay":{"description":"Localization.","type":"string","example":"08:00","nullable":true},"endOfDay":{"description":"Localization.","type":"string","example":"18:00","nullable":true},"preferredServiceLocations":{"description":"Localization.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"assignmentUpdates":{"description":"Notification preference.","type":"boolean","nullable":true},"serviceReminders":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveEmail":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveSms":{"description":"Notification preference.","type":"boolean","nullable":true},"receiveInApp":{"description":"Notification preference.","type":"boolean","nullable":true},"profileShareWithinOrganization":{"description":"Notification preference.","type":"boolean","nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Consumer updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer updated successfully."},"data":{"properties":{"id":{"type":"string","example":"SP-123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed. Includes any org-owned setting sent by the consumer: status, priority, consumerType, portalAccess, isPublished, clientInternalNotes, isSkillOverridden, isCertificationOverridden, isClearanceOverridden, isGenderOverridden, isServiceOverridden, isServiceProviderTypeOverridden, isCommunicationModeOverridden, allowClientsToBroadcastImmediately, assignmentRequest (refused when present, even as null or empty).","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"isPublished":["Your profile status is managed by your organization."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error occurred","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:write","x-fido-module":"consumers","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/cancel-request/{id}":{"post":{"tags":["Requests"],"summary":"Cancel request by ID","operationId":"ext_post_settings_portal_consumer_cancel_request_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the request to cancel","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Request canceled successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request canceled successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request cancellation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["consumer"],"description":"**Required scope:** `requests:write`  \n**Roles:** consumer","x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/hold-request/{id}":{"post":{"tags":["Requests"],"summary":"Hold request by ID","operationId":"ext_post_settings_portal_consumer_hold_request_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the request to hold","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Holded request successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Holded request successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Holding request failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["consumer"],"description":"**Required scope:** `requests:write`  \n**Roles:** consumer","x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/listorganizationclients":{"get":{"tags":["Consumers"],"summary":"List associated organization and clients","description":"**Required scope:** `consumers:read`  \n**Roles:** consumer\n\nClients the signed-in consumer may request service for. Always the caller's own clients; a ?consumer= query parameter is ignored.","operationId":"ext_get_settings_portal_consumer_listorganizationclients","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"responses":{"200":{"description":"Associated organization and clients retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Associated organization and clients Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"P119G2"},"name":{"type":"string","example":"Demo Tenant"},"logo":{"type":"string","nullable":true},"type":{"type":"string","example":"organization"}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Associated organization and clients Retrieved!","data":[{"id":"P119G2","name":"Demo Tenant","logo":null,"type":"organization"}]}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Fetching associated organizations and clients failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/request/document/files":{"delete":{"tags":["Requests"],"summary":"Delete request files by file IDs","operationId":"ext_delete_settings_portal_consumer_request_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileIds":{"type":"array","items":{"type":"string"},"example":["FILE-001","FILE-002"]}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"A listed document was not uploaded by the signed-in user, is not on one of their own requests, or does not exist. Nothing is deleted. A successful delete is recorded in the request's History & Logs.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request files deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:delete","x-fido-module":"requests","x-fido-roles":["consumer"],"description":"**Required scope:** `requests:delete`  \n**Roles:** consumer","x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/request/{id}/{tab}":{"get":{"tags":["Requests"],"summary":"Retrieve specific tab details of a consumer request","description":"**Required scope:** `requests:read`  \n**Roles:** consumer\n\nFetches details for a specific tab (details or sidebar) within a consumer request.","operationId":"ext_get_settings_portal_consumer_request_By_id_By_tab","parameters":[{"name":"id","in":"path","description":"Unique identifier of the request","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"tab","in":"path","description":"Specifies which tab details to fetch","required":true,"schema":{"type":"string","enum":["details","sidebar"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Request tab details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"string","example":"ASM-MARH4E"},"title":{"type":"string","example":"Request Title"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":"ASM-MARH4E","title":"Request Title"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified request does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified request does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/requests":{"get":{"tags":["Requests"],"summary":"Retrieve a list of requests","description":"**Required scope:** `requests:read`  \n**Roles:** consumer\n\nFetches a paginated list of requests based on search criteria, filters, and sorting options.","operationId":"ext_get_settings_portal_consumer_requests","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search query to filter request by name, email, or request Id.","required":false,"schema":{"type":"string","example":"request 1"}},{"name":"location","in":"query","description":"Filter request by location ID.","required":false,"schema":{"type":"string","example":"CLTLOC-123"}},{"name":"duration","in":"query","description":"Filter request by duration.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"serviceTypes","in":"query","description":"Filter request by service Types ID.","required":false,"schema":{"type":"integer","example":"1"}},{"name":"requestedBy","in":"query","description":"Filter request by requester.","required":false,"schema":{"type":"string","example":"consumer"}},{"name":"client","in":"query","description":"Filter assignment by client ID.","required":false,"schema":{"type":"string","example":"CLT-26TR5"}},{"name":"sortBy","in":"query","description":"Sort clients by a specific field (e.g., 'name', 'created_at').","required":false,"schema":{"type":"string","example":"title"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"columns","in":"query","description":"Search query within visible column content.","required":false,"schema":{"type":"string","example":"title,ID,consumer"}},{"name":"startDate","in":"query","required":false,"schema":{"description":"Filter clients created on or after this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"endDate","in":"query","required":false,"schema":{"description":"Filter clients created on or before this date (YYYY-MM-DD).","type":"string","format":"date","example":null}},{"name":"startTime","in":"query","required":false,"schema":{"description":"Filter requests whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime; an overnight range (startTime later than endTime) is handled as spanning midnight.","type":"string","format":"time","example":null}},{"name":"endTime","in":"query","required":false,"schema":{"description":"Filter requests whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.","type":"string","format":"time","example":null}},{"name":"customTab","in":"query","description":"Preset filter tab, applied in addition to any other filters.","required":false,"schema":{"type":"string","enum":["active","archived","past"],"example":"active"}},{"name":"isPublished","in":"query","description":"Filter by publish state: `true` for published requests, `false` for drafts. Omit for both.","required":false,"schema":{"type":"string","enum":["true","false"],"example":"true"}},{"name":"status","in":"query","description":"Filter by request status id.","required":false,"schema":{"type":"integer","example":1}},{"name":"localSearch","in":"query","description":"The table's own search box: matches only the columns named in `columns`. `search` is the global search.","required":false,"schema":{"type":"string"}},{"name":"perPage","in":"query","description":"Rows per page (default: 10).","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"requestSource","in":"query","description":"Filter by the Request Source column (origin of the request).","required":false,"schema":{"type":"string","enum":["client-portal","consumer-portal","scheduler","public-assistant"],"example":"client-portal"}}],"responses":{"200":{"description":"Requests retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"startDate":{"type":"string","example":"2026-01-15","nullable":true},"endDate":{"type":"string","example":"2026-01-15","nullable":true},"startTime":{"type":"string","example":"09:00:00","nullable":true},"endTime":{"type":"string","example":"09:00:00","nullable":true},"convertedStartDate":{"type":"string","example":"2026-01-15"},"convertedEndDate":{"type":"string","example":"2026-01-15"},"convertedStartTime":{"type":"string","example":"09:00:00"},"convertedEndTime":{"type":"string","example":"09:00:00"},"userTimezone":{"type":"string","example":"America/New_York","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"assignmentDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"userDateTooltip":{"type":"string","example":"Jan 15, 2026 9:00 AM – 11:00 AM"},"requestedOn":{"type":"string","example":"2026-01-15"},"submissionDate":{"type":"string","example":"2026-01-15"},"timeSlots":{"properties":{"id":{"type":"integer","example":1},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"09:00:00"}},"type":"object","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid parameters. Ensure all required filters are correct."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":1},"post":{"tags":["Requests"],"summary":"Create a new request","operationId":"ext_post_settings_portal_consumer_requests","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["title","description","requestorName","requestorEmail","requestorPhone","requestorCountryCode","assignTo","client","consumer","timezone","scheduleType","dateTimeSlots"],"properties":{"signinSignoutRequired":{"description":"Providers must sign in and out. Defaults to false.","type":"boolean","example":false,"nullable":true},"title":{"type":"string","example":"Goodk"},"description":{"type":"string","example":"description of the assignment"},"requestorName":{"type":"string","example":"John Doe"},"requestorEmail":{"type":"string","format":"email","example":"user@example.com"},"requestorPhone":{"type":"string","example":"1234567890"},"requestorCountryCode":{"type":"string","example":"+1"},"requestorPhoneType":{"type":"string","example":"mobile"},"requestorPhoneExtension":{"type":"string","example":"123"},"assignTo":{"description":"The only valid value — a consumer submitting a request has no 'organization' option.","type":"string","enum":["client"],"example":"client"},"client":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object"},"consumer":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"},"label":{"type":"string","example":"Consumer Name"}},"type":"object"},"timezone":{"type":"string","example":"America/New_York"},"originOfRequest":{"type":"string","example":"consumer-portal"},"whereServiceRequested":{"properties":{"id":{"type":"string","example":"ORG-12345"},"name":{"type":"string","example":"Dummy Organization"},"logo":{"type":"string","example":"https://example.com/logo.png"},"type":{"type":"string","example":"organization"}},"type":"object"},"scheduleType":{"type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring"},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly"],"example":"daily"},"scheduleInterval":{"type":"integer","example":2},"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Status Label"}},"type":"object"},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object"},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the assignment"},"submittingBehalfOfSomeone":{"type":"boolean","example":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"}},"allowPartialCoverage":{"description":"Providers may cover part of the time. Defaults to false.","type":"boolean","example":false,"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"description":"A document on an assignment, shift or request.","type":"object","allOf":[{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},{"properties":{"isPublic":{"description":"Visible to the client and consumer, not only to staff.","type":"boolean","example":false,"nullable":true}},"type":"object"}]},"nullable":true},"duration":{"description":"Hours.","type":"number","example":1.5,"nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client and consumer","nullable":true},"isPublished":{"description":"Submit the request. False saves a draft, and relaxes most required fields.","type":"boolean","example":true},"location":{"description":"Where a work item happens. `required` rules follow isPublished; onsite and remote are read by locationType: onsite, remote, or both for hybrid.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"Also accepted at the top level as billingOrganizationLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"Also accepted at the top level as billingClientLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Defaults to primary. Also accepted at the top level as billingOption; the nested value wins if both are sent.","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"description":"Required when onSiteType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"description":"Required when onSiteType=client and newClient is not sent.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"description":"Required when onSiteType=manual. Stored as sent.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"addressLine2":{"type":"string","example":"Suite 4","nullable":true},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"},"accessInstruction":{"type":"string","example":"Use the side entrance","nullable":true}},"type":"object","nullable":true},"manualLocationContact":{"description":"Required when onSiteType=manual.","properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"contactPhoneExtension":{"type":"string","example":"123","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"description":"Required when onSiteType=ondemand.","type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"description":"Required when onDemandLocationType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"description":"Required when onDemandLocationType=client.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"description":"Required when onDemandLocationType=manual.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"onDemandManualLocationContact":{"properties":{"contactName":{"type":"string","example":"Jane Roe","nullable":true},"contactEmail":{"type":"string","format":"email","example":"jane@example.test","nullable":true},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"serviceTypes":{"description":"Required unless serviceTypeBreakdown is sent instead.","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"Per-service-type provider counts — alternative to serviceTypes when provider types are being split per service type.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"virtualMeetingSetup":{"description":"Read by consumer portal requests only.","type":"string","nullable":true},"meetingPlatform":{"description":"Required when remoteType is not ondemand.","type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"multiDay":{"description":"Read when scheduleType=multi_day.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"oneTime":{"description":"Read when scheduleType=one_time.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"partialDuration":{"description":"Required when allowPartialCoverage is true.","type":"array","items":{"description":"A window a provider may cover on its own. Windows must tile the work item's time exactly.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-01"},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"10:00:00"}},"type":"object"},"nullable":true},"recurring":{"description":"Read when scheduleType=recurring.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"requireVerifiedTimeDocumentation":{"description":"Providers must sign in and out with a verified time record. Defaults to false.","type":"boolean","example":false,"nullable":true},"requirementAndPreferences":{"type":"array","items":{"description":"Requirements and preferences for one service type on a work item. Rows without serviceType.id are skipped; the list replaces what is stored.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderCertifications":{"description":"Provider type, optionally with a certification it must hold. Pairs that do not belong to the service type are skipped.","type":"array","items":{"properties":{"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certifications":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"skillLevel":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"clearances":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"genderPreference":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true},"isDuplicated":{"description":"Set when this create duplicates an existing record; records a duplication audit event instead of a plain create","type":"boolean","example":false,"nullable":true},"duplicateId":{"description":"The record being duplicated. Read only with isDuplicated=true","type":"string","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Request created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request created successfully"},"data":{"properties":{"id":{"type":"string","example":"ASG-001"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request creation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["consumer"],"description":"**Required scope:** `requests:write`  \n**Roles:** consumer","x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/requests/export":{"get":{"tags":["Requests"],"summary":"Export All Requests to CSV","description":"**Required scope:** `requests:read`  \n**Roles:** consumer  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all requests to an CSV file for download.","operationId":"ext_get_settings_portal_consumer_requests_export","parameters":[{"name":"type","in":"query","description":"Record filter (`all`, `active`, `archived`; default `all`). Also accepted as the output format: `csv` downloads CSV, `xlsx` keeps the default — in which case the record filter falls back to `all`. To use both, keep `type` as the filter and pass `exportType=csv`.","required":false,"schema":{"type":"string","example":"active"}},{"name":"exportType","in":"query","description":"Output format for endpoints where `type` already means something else. On this route `type` is the record filter, so pass the format here: `exportType=csv`. If `type` itself is `csv`/`xlsx` it is read as the format and the record filter falls back to its default.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Type of requests to export. Options: `all` (default), `active`, `archived`.","required":false,"schema":{"type":"string","enum":["all","active","archived"],"example":"active"}}],"responses":{"200":{"description":"CSV file containing requests","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["consumer"],"x-fido-rate-limit":"heavy","x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/requests/export/{id}":{"get":{"tags":["Requests"],"summary":"Export a Single Request to CSV","description":"**Required scope:** `requests:read`  \n**Roles:** consumer  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports a single request to an CSV file for download.","operationId":"ext_get_settings_portal_consumer_requests_export_By_id","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"path","description":"Unique identifier of the request to export.","required":true,"schema":{"type":"string","example":"ASG-45FDX"}}],"responses":{"200":{"description":"CSV file containing request","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:read","x-fido-module":"requests","x-fido-roles":["consumer"],"x-fido-rate-limit":"heavy","x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/requests/{id}":{"delete":{"tags":["Requests"],"summary":"Delete a request","description":"**Required scope:** `requests:delete`  \n**Roles:** consumer\n\nDeletes a request by ID for the given tenant, including child requests and associated files from S3.","operationId":"ext_delete_settings_portal_consumer_requests_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"ID of the request to delete","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Request deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Request not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Request not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:delete","x-fido-module":"requests","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":1},"post":{"tags":["Requests"],"summary":"Update an existing request","operationId":"ext_post_settings_portal_consumer_requests_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the request to be updated","required":true,"schema":{"type":"string","example":"ASG-SA2IVL"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["title","description","requestorName","requestorEmail","requestorPhone","requestorCountryCode","assignTo","client","consumer","timezone","scheduleType","dateTimeSlots"],"properties":{"title":{"type":"string","example":"Goodk"},"description":{"type":"string","example":"description of the assignment"},"requestorName":{"type":"string","example":"John Doe"},"requestorEmail":{"type":"string","format":"email","example":"user@example.com"},"requestorPhone":{"type":"string","example":"1234567890"},"requestorCountryCode":{"type":"string","example":"+1"},"requestorPhoneType":{"type":"string","example":"mobile"},"requestorPhoneExtension":{"type":"string","example":"123"},"assignTo":{"description":"Must be client; organization is not accepted.","type":"string","enum":["client"],"example":"client"},"client":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object"},"consumer":{"properties":{"id":{"type":"string","example":"CSM-SQEWP0T"},"label":{"type":"string","example":"Consumer Name"}},"type":"object"},"timezone":{"type":"string","example":"America/New_York"},"originOfRequest":{"type":"string","example":"consumer-portal"},"whereServiceRequested":{"properties":{"id":{"type":"string","example":"ORG-12345"},"name":{"type":"string","example":"Dummy Organization"},"logo":{"type":"string","example":"https://example.com/logo.png"},"type":{"type":"string","example":"organization"}},"type":"object"},"scheduleType":{"type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring"},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly"],"example":"daily"},"scheduleInterval":{"type":"integer","example":2},"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}},"status":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Status Label"}},"type":"object"},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object"},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"}},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the assignment"},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"}},"allowPartialCoverage":{"description":"Providers may cover part of the time. Defaults to false.","type":"boolean","example":false,"nullable":true},"customFields":{"description":"Custom field values keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"description":"A document on an assignment, shift or request.","type":"object","allOf":[{"description":"One document row in a multipart save. Send `id` to keep or update an existing document; omit it to upload a new one.","properties":{"id":{"type":"integer","example":12,"nullable":true},"file":{"description":"The uploaded file. Omit when only the categories or tags of an existing document change.","type":"string","format":"binary","nullable":true},"fileName":{"type":"string","example":"intake-form.pdf","nullable":true},"categories":{"description":"Existing categories by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"tags":{"description":"Existing tags by `id`, or new ones by `label`.","type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}},"type":"object"},{"properties":{"isPublic":{"description":"Visible to the client and consumer, not only to staff.","type":"boolean","example":false,"nullable":true}},"type":"object"}]},"nullable":true},"duration":{"description":"Hours.","type":"number","example":1.5,"nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client and consumer","nullable":true},"isPublished":{"description":"Submit the request. False saves a draft, and relaxes most required fields.","type":"boolean","example":true},"location":{"description":"Where a work item happens. `required` rules follow isPublished; onsite and remote are read by locationType: onsite, remote, or both for hybrid.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"Also accepted at the top level as billingOrganizationLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"Also accepted at the top level as billingClientLocationId; the top-level value wins if both are sent.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Defaults to primary. Also accepted at the top level as billingOption; the nested value wins if both are sent.","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"description":"Required when onSiteType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"description":"Required when onSiteType=client and newClient is not sent.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"description":"Required when onSiteType=manual. Stored as sent.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"addressLine2":{"type":"string","example":"Suite 4","nullable":true},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"},"accessInstruction":{"type":"string","example":"Use the side entrance","nullable":true}},"type":"object","nullable":true},"manualLocationContact":{"description":"Required when onSiteType=manual.","properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneType":{"type":"string","example":"sms_and_voice","nullable":true},"contactPhoneExtension":{"type":"string","example":"123","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"description":"Required when onSiteType=ondemand.","type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"description":"Required when onDemandLocationType=organization.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"description":"Required when onDemandLocationType=client.","properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"description":"Required when onDemandLocationType=manual.","properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"onDemandManualLocationContact":{"properties":{"contactName":{"type":"string","example":"Jane Roe","nullable":true},"contactEmail":{"type":"string","format":"email","example":"jane@example.test","nullable":true},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"serviceTypes":{"description":"Required unless serviceTypeBreakdown is sent instead.","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"Per-service-type provider counts — alternative to serviceTypes when provider types are being split per service type.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"virtualMeetingSetup":{"description":"Read by consumer portal requests only.","type":"string","nullable":true},"meetingPlatform":{"description":"Required when remoteType is not ondemand.","type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}},"serviceProviderType":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"nullable":true}},"type":"object","nullable":true}},"type":"object"},"multiDay":{"description":"Read when scheduleType=multi_day.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"oneTime":{"description":"Read when scheduleType=one_time.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"priority":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"recurring":{"description":"Read when scheduleType=recurring.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object"},"requireVerifiedTimeDocumentation":{"description":"Providers must sign in and out with a verified time record. Defaults to false.","type":"boolean","example":false,"nullable":true},"requirementAndPreferences":{"type":"array","items":{"description":"Requirements and preferences for one service type on a work item. Rows without serviceType.id are skipped; the list replaces what is stored.","properties":{"serviceType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"serviceProviderCertifications":{"description":"Provider type, optionally with a certification it must hold. Pairs that do not belong to the service type are skipped.","type":"array","items":{"properties":{"serviceProviderType":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"certifications":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}},"skillLevel":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"clearances":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"specializations":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"genderPreference":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"},"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Request updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request created successfully"},"data":{"properties":{"id":{"type":"string","example":"ASG-SA2IVL"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'requests:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Request updation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"requests:write","x-fido-module":"requests","x-fido-roles":["consumer"],"description":"**Required scope:** `requests:write`  \n**Roles:** consumer","x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/consumer/{tab}":{"get":{"tags":["Consumers"],"summary":"Retrieve specific tab details of a consumer portal","description":"**Required scope:** `consumers:read`  \n**Roles:** consumer\n\nFetches the details for a specific tab within a consumer portal based on the authenticated user. Supports optional filtering by client name or relationship name.","operationId":"ext_get_settings_portal_consumer_By_tab","parameters":[{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details', 'localizations', 'associated_service_organizations','notifications_access','requirements_preferences')","required":true,"schema":{"type":"string","enum":["details","localizations","associated_service_organizations","notifications_access","requirements_preferences"],"example":"details"}},{"name":"client","in":"query","description":"Filter associated clients by client ID","required":false,"schema":{"type":"string","example":"CLT-123456"}},{"name":"relationship","in":"query","description":"Filter associated clients by relationship ID","required":false,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Consumer portal details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer details retrieved!"},"data":{"properties":{"id":{"type":"string","example":"CSM-PDZTZ9"},"name":{"type":"string","example":"test"},"description":{"type":"string","example":"I am doing testing"},"email":{"type":"string","example":"user@example.com"},"logo":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg"},"countryCode":{"type":"string","example":"+1"},"phone":{"type":"string","example":"9786159228"},"phoneExtension":{"type":"string","example":"null"},"phoneType":{"type":"string","example":"sms_and_voice"},"videoPhoneCountryCode":{"type":"string","example":"+1"},"videoPhone":{"type":"string","example":"9786159226"},"addressLine1":{"type":"string","example":"123 Bark Street"},"addressLine2":{"type":"string","example":"3434 Street"},"city":{"type":"string","example":"Austin1"},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","example":"33629"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Consumer details retrieved!","data":{"id":"CSM-PDZTZ9","name":"test","description":"I am doing testing","email":"user@example.com","logo":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg","countryCode":"+1","phone":"9786159228","phoneExtension":"null","phoneType":"sms_and_voice","videoPhoneCountryCode":"+1","videoPhone":"9786159226","addressLine1":"123 Bark Street","addressLine2":"3434 Street","city":"Austin1","state":null,"postalCode":"33629"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'consumers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified consumer portal does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified consumer portal does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"consumers:read","x-fido-module":"consumers","x-fido-roles":["consumer"],"x-fido-area":"Consumer portal","x-fido-area-rank":1}},"/v1/settings/portal/preference-list":{"get":{"tags":["Settings · Preferred Users"],"summary":"Retrieve paginated preference list with optional filters","description":"**Required scope:** `settings_preferred_users:read`  \n**Roles:** client, consumer, service-provider\n\nFetch a paginated list of preference list entries. Allows filtering, searching, and sorting.","operationId":"ext_get_settings_portal_preference_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"columns","in":"query","schema":{"type":"string"}},{"name":"sortBy","in":"query","schema":{"type":"string"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","schema":{"type":"integer"}},{"name":"clientId","in":"query","schema":{"type":"string"}},{"name":"consumerId","in":"query","schema":{"type":"string"}},{"name":"serviceProviderId","in":"query","schema":{"type":"string"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"preferredUser":{"properties":{"id":{"type":"string","example":"CLT-XXISS8"},"label":{"type":"string","example":"Client2"}},"type":"object"},"preferredUserRoleName":{"type":"string","example":"admin","nullable":true},"preferredRole":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Client"},"slug":{"type":"string","example":"client"}},"type":"object"},"preferredUserImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"preferredUserOnlineStatus":{"type":"string","example":"online"},"notes":{"type":"string","example":"Added by the scheduler.","nullable":true},"preferredDate":{"type":"string","example":"2026-01-15"},"isBehalfOfOrg":{"type":"boolean","example":true},"isBehalfOfRole":{"type":"string","nullable":true},"providerServices":{"type":"array","items":[],"nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"object","example":{"search":["Invalid search parameter"]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:read","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Preferred list","x-fido-area-rank":0},"post":{"tags":["Settings · Preferred Users"],"summary":"Create a new preference entry","operationId":"ext_post_settings_portal_preference_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["preferredUser"],"properties":{"preferredUser":{"required":["id","label"],"properties":{"id":{"description":"ID of the user being preferred","type":"string","example":"SPR-EDUHU"},"label":{"description":"Role of the user being preferred","type":"string","example":"Service Provider"}},"type":"object"},"notes":{"type":"string","example":"Demo","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Preference successfully created","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"John Doe has been added to preferences by Jane Smith."}},"type":"object"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"preferredUser":["You can only prefer a Service Provider."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Preference list creation failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:write","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"description":"**Required scope:** `settings_preferred_users:write`  \n**Roles:** client, consumer, service-provider","x-fido-area":"Preferred list","x-fido-area-rank":0}},"/v1/settings/portal/preference-list-export":{"get":{"tags":["Settings · Preferred Users"],"summary":"Export preference list to Excel","description":"**Required scope:** `settings_preferred_users:read`  \n**Roles:** client, consumer, service-provider  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports the full preference list to an Excel (.xlsx) file for download.","operationId":"ext_get_settings_portal_preference_list_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"id","in":"query","description":"Optional ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing preference list data","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference list export failed. Please try again later."}},"type":"object"},"example":{"success":false,"message":"Preference list export failed. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:read","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-rate-limit":"heavy","x-fido-area":"Preferred list","x-fido-area-rank":0}},"/v1/settings/portal/preference-list-filter-options":{"get":{"tags":["Settings · Preferred Users"],"summary":"Get preferred list filter options","description":"**Required scope:** `settings_preferred_users:read`  \n**Roles:** client, consumer, service-provider\n\nReturns categorized filter options (clients, consumers, providers) from the preferred list.","operationId":"ext_get_settings_portal_preference_list_filter_options","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"module","in":"query","description":"The caller's portal role. Picks which groups are filled: `client` and `consumer` return providers only, `service-provider` returns all three. Omitted, every group comes back empty.","required":false,"schema":{"type":"string","enum":["client","consumer","service-provider"],"example":"client"}}],"responses":{"200":{"description":"Successfully retrieved filter options","content":{"application/json":{"schema":{"properties":{"clients":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-GGM6R1"},"label":{"type":"string","example":"Client1"},"image":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-RVQLPP/689477ec21a93_Test.jpg"}},"type":"object"}},"consumers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-YWUOOH"},"label":{"type":"string","example":"Consumer1"},"image":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-AZEKLZ/68b97388cabd8_Test.jpg"}},"type":"object"}},"providers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-WHWVON"},"label":{"type":"string","example":"ServiceProvider2"},"image":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg"}},"type":"object"}}},"type":"object"},"example":{"clients":[{"id":"CLT-GGM6R1","label":"Client1","image":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-RVQLPP/689477ec21a93_Test.jpg"}],"consumers":[{"id":"CSM-YWUOOH","label":"Consumer1","image":"https://d3t50b2fzyr6w1.cloudfront.net/organizations/ORG-LQEKFW/clients/CLT-AZEKLZ/68b97388cabd8_Test.jpg"}],"providers":[{"id":"SPR-WHWVON","label":"ServiceProvider2","image":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg"}]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:read","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Preferred list","x-fido-area-rank":0}},"/v1/settings/portal/preference-list/{preference_list}":{"delete":{"tags":["Settings · Preferred Users"],"summary":"Delete a preference entry from the list","description":"**Required scope:** `settings_preferred_users:delete`  \n**Roles:** client, consumer, service-provider\n\nDeletes a preferred list entry by its ID. If the ID does not exist, a 404 error will be returned.","operationId":"ext_delete_settings_portal_preference_list_By_preference_list","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant-specific header key","required":true,"schema":{"type":"string","example":"tenant_abc"}},{"name":"preference_list","in":"path","description":"ID of the preference entry to delete","required":true,"schema":{"type":"integer","example":42}}],"responses":{"200":{"description":"Successfully removed from preference list","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"User has been removed from your preference list."}},"type":"object"}}}},"400":{"description":"Validation failed (e.g., invalid ID)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to delete."},"errors":{"type":"object","example":{"id":["The given ID is invalid or missing."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Preference deletion failed: [error details].","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:delete","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Preferred list","x-fido-area-rank":0},"get":{"tags":["Settings · Preferred Users"],"summary":"Retrieve a specific preference list entry","description":"**Required scope:** `settings_preferred_users:read`  \n**Roles:** client, consumer, service-provider\n\nFetches a single preference list entry based on the provided ID.","operationId":"ext_get_settings_portal_preference_list_By_preference_list","parameters":[{"name":"preference_list","in":"path","description":"ID of the preference list entry","required":true,"schema":{"type":"integer","example":10}},{"name":"X-Tenant-ID","in":"header","description":"Tenant-specific header key","required":true,"schema":{"type":"string","example":"TNT-XYZ123"}}],"responses":{"200":{"description":"Preference entry retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Preference List entry retrieved."},"data":{"properties":{"id":{"type":"integer","example":1},"preferredUser":{"properties":{"id":{"type":"string","example":"SPR-AJKF8"},"label":{"type":"string","example":"John Service"}},"type":"object"},"preferredUserRoleName":{"type":"string","example":"admin","nullable":true},"preferredRole":{"properties":{"id":{"type":"integer","example":1,"nullable":true},"label":{"type":"string","example":"Example label","nullable":true},"slug":{"type":"string","example":"example-slug","nullable":true}},"type":"object","nullable":true},"preferredUserImage":{"type":"string","example":"https://cdn.example.com/image.png","nullable":true},"preferredUserOnlineStatus":{"type":"string","example":"online"},"notes":{"type":"string","example":"Added by the scheduler.","nullable":true},"preferredDate":{"type":"string","example":"2026-01-15"},"isBehalfOfOrg":{"type":"boolean","example":true},"isBehalfOfRole":{"type":"string","nullable":true},"providerServices":{"type":"array","items":[],"nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Preference entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference List entry not found."},"errors":{"type":"string","example":null}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Internal server exception message","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:read","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"x-fido-area":"Preferred list","x-fido-area-rank":0},"put":{"tags":["Settings · Preferred Users"],"summary":"Update a preference entry (notes, preferredBy, preferredUser)","operationId":"ext_put_settings_portal_preference_list_By_preference_list","parameters":[{"name":"preference_list","in":"path","description":"ID of the preference entry to update","required":true,"schema":{"type":"integer","example":123}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"tenant_001"}}],"requestBody":{"description":"Any of the fields (notes, preferredBy, preferredUser) can be updated.","required":true,"content":{"application/json":{"schema":{"properties":{"preferredUser":{"properties":{"id":{"type":"integer","example":202},"label":{"type":"string","example":"Jane Smith"}},"type":"object","nullable":true},"notes":{"description":"Optional notes (max 255 characters)","type":"string","example":"Updated reason for preference","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Preference entry updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Preference List updated!"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Preference entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:edit","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"description":"**Required scope:** `settings_preferred_users:edit`  \n**Roles:** client, consumer, service-provider","x-fido-area":"Preferred list","x-fido-area-rank":0},"patch":{"tags":["Settings · Preferred Users"],"summary":"Update a preference entry (notes, preferredBy, preferredUser)","operationId":"ext_patch_settings_portal_preference_list_By_preference_list","parameters":[{"name":"preference_list","in":"path","description":"ID of the preference entry to update","required":true,"schema":{"type":"integer","example":123}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"tenant_001"}}],"requestBody":{"description":"Any of the fields (notes, preferredBy, preferredUser) can be updated.","required":true,"content":{"application/json":{"schema":{"properties":{"preferredUser":{"properties":{"id":{"type":"integer","example":202},"label":{"type":"string","example":"Jane Smith"}},"type":"object","nullable":true},"notes":{"description":"Optional notes (max 255 characters)","type":"string","example":"Updated reason for preference","nullable":true},"isBehalfOfOrg":{"description":"Record the entry on behalf of the organization rather than the caller. Defaults to false.","type":"boolean","example":false,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Preference entry updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Preference List updated!"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_preferred_users:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Preference entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Preference entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_preferred_users:edit","x-fido-module":"settings_preferred_users","x-fido-roles":["client","consumer","service-provider"],"description":"**Required scope:** `settings_preferred_users:edit`  \n**Roles:** client, consumer, service-provider","x-fido-area":"Preferred list","x-fido-area-rank":0}},"/v1/settings/portal/provider/assignment":{"get":{"tags":["Assignments"],"summary":"Retrieve service provider assignments","description":"**Required scope:** `assignments:read`  \n**Roles:** service-provider\n\nFetches a paginated list of assignments for the authenticated service provider based on filters. Each item adds myTime and myConvertedTime: the provider's own covered hours on that occurrence when they hold only part of a partial-coverage job ('12:00 PM to 4:00 PM', separate runs joined with ', '), null otherwise.","operationId":"ext_get_settings_portal_provider_assignment","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"search","in":"query","description":"Search query to filter assignments by name, email, or assignment ID.","required":false,"schema":{"type":"string","example":"assignment 1"}},{"name":"status","in":"query","description":"Filter assignments by status ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"serviceTypes","in":"query","description":"Filter assignments by service type ID.","required":false,"schema":{"type":"integer","example":1}},{"name":"client","in":"query","description":"Filter assignments by client ID.","required":false,"schema":{"type":"string","example":"CLT-567FGR"}},{"name":"customTab","in":"query","description":"Filter assignments by custom tab.","required":false,"schema":{"type":"string","example":"active"}},{"name":"startDate","in":"query","description":"Filter assignments starting on or after this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2024-01-01"}},{"name":"endDate","in":"query","description":"Filter assignments ending on or before this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date","example":"2024-12-31"}},{"name":"startTime","in":"query","description":"Filter assignments by start time.","required":false,"schema":{"type":"string","example":"09:00"}},{"name":"endTime","in":"query","description":"Filter assignments by end time.","required":false,"schema":{"type":"string","example":"17:00"}},{"name":"locationType","in":"query","description":"Filter assignments by location type.","required":false,"schema":{"type":"string","example":"remote"}},{"name":"duration","in":"query","description":"Filter assignments by duration in hours.","required":false,"schema":{"type":"integer","example":8}},{"name":"distance","in":"query","description":"Filter assignments by distance in miles/km.","required":false,"schema":{"type":"number","format":"float","example":25.5}},{"name":"sortBy","in":"query","description":"Sort assignments by a specific field (e.g., 'name', 'created_at').","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sorting order: ascending ('asc') or descending ('desc').","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of assignments to retrieve per page.","required":false,"schema":{"type":"integer","example":10}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search within.","required":false,"schema":{"type":"string","example":"name,status,priority"}},{"name":"partialCover","in":"query","description":"Filter by the Partial Cover column: true for work items that allow partial coverage, false for those that do not.","required":false,"schema":{"type":"boolean","example":true}},{"name":"requestSource","in":"query","description":"Filter by the Request Source column (origin of the request).","required":false,"schema":{"type":"string","enum":["client-portal","consumer-portal","scheduler","public-assistant"],"example":"client-portal"}}],"responses":{"200":{"description":"Assignments retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment List Retrieved!"},"data":{"type":"array","items":{"properties":{"assignmentId":{"type":"string","example":"ASG-23RT45"},"name":{"type":"string","example":"Assignment Name"},"status":{"type":"string","example":"Active"},"priority":{"type":"string","example":"High"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request - Invalid query parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"string","example":"Invalid parameters provided."}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/settings/portal/provider/assignment/assignment-complete/{id}":{"post":{"tags":["Assignments"],"summary":"Mark assignment as complete","description":"**Required scope:** `assignments:write`  \n**Roles:** service-provider\n\nAllows the service provider assigned to an assignment or shift to mark their part of it as completed. A provider with no assigned row on this work item gets 403.","operationId":"ext_post_settings_portal_provider_assignment_assignment_complete_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"Unique identifier of the assignment to mark as complete.","required":true,"schema":{"type":"string","example":"ASG-23RT45"}}],"responses":{"200":{"description":"Assignment marked as complete successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"description":"':entity :name (:id) was marked as complete.' — entity is Assignment or Shift, name is the title (the id when it has none)","type":"string","example":"Assignment Morning interpreting (ASG-23RT45) was marked as complete."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"400":{"description":"Assignment cannot be marked as complete. Two cases, each with its own message/errors pair: already completed ('This assignment has already been completed.' / 'Action not allowed'); before the scheduled end time ('Action not allowed' / 'You can complete the assignment only after the scheduled end time.').","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Action not allowed"},"errors":{"type":"string","example":"You can complete the assignment only after the scheduled end time."},"code":{"type":"string","example":""}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The caller is not an assigned provider on this assignment or shift, or no work item has this id","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"The work item requires verified time documentation and the caller's sign-in/sign-out is incomplete. errors.missing_fields lists the empty check-in fields — all eight when the caller has no check-in at all.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Sign in & out fields are required."},"errors":{"properties":{"missing_fields":{"type":"array","items":{"type":"string","enum":["sign_in_date","sign_in_time","sign_out_date","sign_out_time","sign_in_sign","sign_in_by","sign_out_sign","sign_out_by"]},"example":["sign_out_date","sign_out_time","sign_out_sign","sign_out_by"]}},"type":"object"},"code":{"type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to complete assignment"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:write","x-fido-module":"assignments","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/settings/portal/provider/assignment/provider-expenses":{"post":{"tags":["Assignments"],"summary":"Store or update assignment expenses","description":"**Required scope:** `assignments:write`  \n**Roles:** service-provider\n\nA service provider adds or updates their own expense lines on an assignment or shift. Rows with an id update that expense; rows without one create a new line. Send multipart/form-data to attach receipts (expenses[N][uploadReceipt] or expenses[N][document]), or JSON without files. The route is open to the service-provider role only.","operationId":"ext_post_settings_portal_provider_assignment_provider_expenses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["expenses"],"properties":{"expenses":{"type":"array","items":{"description":"One expense line. Name it one of three ways: reimbursableExpenseId (a template line on the work item); sourceReimbursableExpense or categoryId plus customName/name (a custom line seeded from a catalog category); or customName/name alone (a freeform custom line, which needs expense or amount). reimbursableExpenseId and a source category together are refused.","required":["assignmentId","serviceProviderId"],"properties":{"id":{"description":"Existing provider expense id to update; omit to create. A row with id 'reimbursable-basic' (the read-only aggregate row of the provider view) is dropped.","type":"integer","example":42,"nullable":true},"assignmentId":{"description":"Work item id, ASG-* or SFT-*. The first row's prefix decides whether every row is checked against assignments or shifts.","type":"string","example":"ASG-23RT45"},"serviceProviderId":{"description":"Must be an existing service provider id. The first row's value must be the caller's own id.","type":"string","example":"SPR-ABC123"},"reimbursableExpenseId":{"description":"Catalog expense id of a template line attached to the work item","type":"integer","example":7,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from. May also be sent as a JSON string (multipart). The legacy flat sourceReimbursableExpenseId is not accepted.","properties":{"id":{"type":"integer","example":7},"label":{"type":"string","example":"Mileage","nullable":true}},"type":"object","nullable":true},"categoryId":{"description":"Bare alternative to sourceReimbursableExpense.id","type":"integer","example":7,"nullable":true},"customName":{"type":"string","minLength":1,"example":"Parking","nullable":true},"name":{"description":"Accepted in place of customName","type":"string","minLength":1,"example":"Parking","nullable":true},"isDefault":{"description":"Used with name to resolve whether a name means a template line or a custom one","type":"boolean","example":false,"nullable":true},"expenseType":{"description":"Classification of a freeform custom line","type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"example":"travel","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom line; defaults to flat_amount when only expenseType is sent","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"flat_amount","nullable":true},"rate":{"description":"Rate for a freeform custom line's basis","type":"number","format":"float","example":0.67,"nullable":true},"unit":{"description":"Unit for a per_unit freeform custom line","type":"string","example":"mile","nullable":true},"maximumReimbursementCap":{"description":"Cap for a freeform custom line","type":"number","format":"float","example":100,"nullable":true},"expense":{"description":"Reimbursement payout; overrides the calculated amount","type":"number","format":"float","minimum":0.01,"example":25.5,"nullable":true},"amount":{"description":"Submitted cost (the receipt amount), which percentage categories calculate from","type":"number","format":"float","minimum":0.01,"example":40,"nullable":true},"quantity":{"description":"Units for per_unit / per_day lines","type":"number","format":"float","minimum":0.01,"example":12,"nullable":true},"billTo":{"description":"Who the line is billed to; an existing line keeps its own when this is omitted","type":"string","enum":["organization","client"],"example":"client","nullable":true},"status":{"description":"Only pending is accepted; omit to keep an existing line's status","type":"string","enum":["pending"],"example":"pending"},"uploadReceipt":{"description":"Receipt file (multipart). Some catalog categories require one.","type":"string","format":"binary","nullable":true},"document":{"description":"Alternative receipt field (multipart): pdf, jpg, jpeg or png, at most 2 MB","type":"string","format":"binary","nullable":true}},"type":"object"},"minItems":1}},"type":"object"}},"multipart/form-data":{"schema":{"required":["expenses"],"properties":{"expenses":{"type":"array","items":{"description":"One expense line. Name it one of three ways: reimbursableExpenseId (a template line on the work item); sourceReimbursableExpense or categoryId plus customName/name (a custom line seeded from a catalog category); or customName/name alone (a freeform custom line, which needs expense or amount). reimbursableExpenseId and a source category together are refused.","required":["assignmentId","serviceProviderId"],"properties":{"id":{"description":"Existing provider expense id to update; omit to create. A row with id 'reimbursable-basic' (the read-only aggregate row of the provider view) is dropped.","type":"integer","example":42,"nullable":true},"assignmentId":{"description":"Work item id, ASG-* or SFT-*. The first row's prefix decides whether every row is checked against assignments or shifts.","type":"string","example":"ASG-23RT45"},"serviceProviderId":{"description":"Must be an existing service provider id. The first row's value must be the caller's own id.","type":"string","example":"SPR-ABC123"},"reimbursableExpenseId":{"description":"Catalog expense id of a template line attached to the work item","type":"integer","example":7,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from. May also be sent as a JSON string (multipart). The legacy flat sourceReimbursableExpenseId is not accepted.","properties":{"id":{"type":"integer","example":7},"label":{"type":"string","example":"Mileage","nullable":true}},"type":"object","nullable":true},"categoryId":{"description":"Bare alternative to sourceReimbursableExpense.id","type":"integer","example":7,"nullable":true},"customName":{"type":"string","minLength":1,"example":"Parking","nullable":true},"name":{"description":"Accepted in place of customName","type":"string","minLength":1,"example":"Parking","nullable":true},"isDefault":{"description":"Used with name to resolve whether a name means a template line or a custom one","type":"boolean","example":false,"nullable":true},"expenseType":{"description":"Classification of a freeform custom line","type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"example":"travel","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom line; defaults to flat_amount when only expenseType is sent","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"flat_amount","nullable":true},"rate":{"description":"Rate for a freeform custom line's basis","type":"number","format":"float","example":0.67,"nullable":true},"unit":{"description":"Unit for a per_unit freeform custom line","type":"string","example":"mile","nullable":true},"maximumReimbursementCap":{"description":"Cap for a freeform custom line","type":"number","format":"float","example":100,"nullable":true},"expense":{"description":"Reimbursement payout; overrides the calculated amount","type":"number","format":"float","minimum":0.01,"example":25.5,"nullable":true},"amount":{"description":"Submitted cost (the receipt amount), which percentage categories calculate from","type":"number","format":"float","minimum":0.01,"example":40,"nullable":true},"quantity":{"description":"Units for per_unit / per_day lines","type":"number","format":"float","minimum":0.01,"example":12,"nullable":true},"billTo":{"description":"Who the line is billed to; an existing line keeps its own when this is omitted","type":"string","enum":["organization","client"],"example":"client","nullable":true},"status":{"description":"Only pending is accepted; omit to keep an existing line's status","type":"string","enum":["pending"],"example":"pending"},"uploadReceipt":{"description":"Receipt file (multipart). Some catalog categories require one.","type":"string","format":"binary","nullable":true},"document":{"description":"Alternative receipt field (multipart): pdf, jpg, jpeg or png, at most 2 MB","type":"string","format":"binary","nullable":true}},"type":"object"},"minItems":1}},"type":"object"}}}},"responses":{"200":{"description":"Expenses saved","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expenses submitted for review."},"data":{"type":"object","example":null,"nullable":true}},"type":"object"}}}},"400":{"description":"The caller has already completed the work item named by the first row","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"This assignment has already been completed."},"errors":{"type":"string","example":"Action not allowed"},"code":{"type":"string","example":""}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The first row's serviceProviderId is not the caller","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Two shapes. Field validation uses this endpoint's own body — status/message/errors, no success key, one message per field. A rule the save itself refuses (for example editing the amount of an approved line) comes back in the standard envelope with the same text in message and errors.","content":{"application/json":{"schema":{"oneOf":[{"description":"Field validation","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"expenses.0.customName":"Custom name is required when reimbursableExpenseId is not provided and must be at least 1 character."},"additionalProperties":{"type":"string"}}},"type":"object"},{"description":"Refused by the save","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Approved expenses cannot be edited. Revoke approval before changing quantity or amount."},"errors":{"type":"string","example":"Approved expenses cannot be edited. Revoke approval before changing quantity or amount."},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error. A new expense added after the work item's expense submission deadline also lands here, with the same generic message.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"type":"string","example":null,"nullable":true},"code":{"type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:write","x-fido-module":"assignments","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/settings/portal/provider/assignment/{id}":{"get":{"tags":["Assignments"],"summary":"Retrieve single assignment details","description":"**Required scope:** `assignments:read`  \n**Roles:** service-provider\n\nFetches detailed information about a specific assignment for the service provider. When the provider holds only part of a partial-coverage job, myTime and myConvertedTime carry their own covered hours ('12:00 PM to 4:00 PM', separate runs joined with ', ') in the work item's and the provider's timezone; both are null when they hold the whole job.","operationId":"ext_get_settings_portal_provider_assignment_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"Unique identifier of the assignment.","required":true,"schema":{"type":"string","example":"ASG-23RT45"}}],"responses":{"200":{"description":"Assignment details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment data retrieved successfully."},"data":{"properties":{"assignmentId":{"type":"string","example":"ASG-23RT45"},"title":{"type":"string","example":"Assignment Title"},"description":{"type":"string","example":"Assignment description"},"status":{"type":"string","example":"Active"},"priority":{"type":"string","example":"High"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Not Found"},"errors":{"type":"string","example":"Assignment data not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/settings/portal/provider/assignment/{id}/slots":{"get":{"tags":["Assignments"],"summary":"Get assignment available slots","description":"**Required scope:** `assignments:read`  \n**Roles:** service-provider\n\nFetch assignment slots grouped by service type and provider type for provider coverage selection.","operationId":"ext_get_settings_portal_provider_assignment_By_id_slots","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"Unique identifier of the assignment or shift.","required":true,"schema":{"type":"string","example":"ASG-TQBTH1"}}],"responses":{"200":{"description":"Assignment slots retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment slots retrieved successfully."},"data":{"properties":{"assignmentId":{"type":"string","example":"ASG-TQBTH1"},"startDate":{"type":"string","format":"date","example":"2026-04-24"},"endDate":{"type":"string","format":"date","example":"2026-04-24"},"locationType":{"type":"string","example":"hybrid"},"slots":{"type":"array","items":{"properties":{"slotId":{"type":"integer","example":655},"startTime":{"type":"string","example":"12:00 PM"},"endTime":{"type":"string","example":"1:00 PM"},"isFilled":{"type":"boolean","example":false},"serviceTypeBreakdowns":{"type":"array","items":{"properties":{"assignmentLocationServiceTypeId":{"type":"integer","example":1020},"locationType":{"type":"string","example":"remote"},"serviceTypeName":{"type":"string","example":"CART"},"isFilled":{"type":"boolean","example":false},"providerTypes":{"type":"array","items":{"properties":{"assignmentLocationProviderTypeId":{"type":"integer","example":1529},"providerTypeName":{"type":"string","example":"Captioner"},"isFilled":{"type":"boolean","example":false},"alreadyExists":{"type":"boolean","example":true},"existingRecord":{"properties":{"id":{"type":"integer","example":658},"status":{"type":"string","example":"canceled"}},"type":"object","nullable":true}},"type":"object"}}},"type":"object"}}},"type":"object"}}},"type":"object"}},"type":"object"}}}},"400":{"description":"Assignment already completed or action not allowed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"This assignment has already been completed."}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Assignment not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Assignment not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:read","x-fido-module":"assignments","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/settings/portal/provider/assignment/{type}/{id}":{"patch":{"tags":["Assignments"],"summary":"Withdraw or edit coverage for an assignment","description":"**Required scope:** `assignments:edit`  \n**Roles:** service-provider\n\nAllows service providers to withdraw from an assignment or edit their coverage details.","operationId":"ext_patch_settings_portal_provider_assignment_By_type_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"type","in":"path","description":"Type of action: 'withdraw' to withdraw from assignment or 'edit-coverage' to edit coverage.","required":true,"schema":{"type":"string","enum":["withdraw","edit-coverage"],"example":"withdraw"}},{"name":"id","in":"path","description":"Unique identifier of the assignment.","required":true,"schema":{"type":"string","example":"ASG-23RT45"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"removeSlots":{"description":"Slots the provider is giving up. Read with type=edit-coverage. type=withdraw ignores it and withdraws the provider from every slot.","type":"array","items":{"properties":{"slotId":{"description":"Required when type=edit-coverage.","type":"integer","example":41},"locationTypeId":{"description":"Required when type=edit-coverage.","type":"integer","example":12},"providerTypeId":{"type":"integer","example":3,"nullable":true},"assignmentProviderId":{"type":"integer","example":88,"nullable":true}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Assignment action completed successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment withdraw successully"}},"type":"object"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"The authenticated provider has no relationship to this assignment/shift (never invited, never assigned) — generic message on purpose, so the response can't be used to tell a real id apart from one belonging to someone else.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. For type=edit-coverage, each removeSlots entry's slotId, locationTypeId and providerTypeId are cross-referenced against the assignment/shift named in {id} — a real id that belongs to a different assignment is rejected here, not silently written against the wrong one.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation failed"},"errors":{"type":"object","example":{"removeSlots.0.slotId":["This slot does not belong to this assignment."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to withdraw assignment"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/settings/portal/provider/network-rates":{"post":{"tags":["Settings · Rates & Billing"],"summary":"Create and update service provider portal network rates","description":"**Required scope:** `settings_rates_billing:write`  \n**Roles:** service-provider\n\nCreate and update a service provider portal network rates by auth user the given payload.","operationId":"ext_post_settings_portal_provider_network_rates","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_001"}}],"requestBody":{"description":"Service Provider network rates create and update payload","required":true,"content":{"application/json":{"schema":{"properties":{"rates":{"type":"array","items":{"properties":{"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Standard"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Deaf"}},"type":"object"},"certification":{"properties":{"id":{"type":"integer","example":7},"label":{"type":"string","example":"BEI DI"},"isCustom":{"type":"boolean","example":null,"nullable":true}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"onsite_client"},"label":{"type":"string","example":"On-Site (Client)"}},"type":"object"},"specialization":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"},"unit":{"type":"string","example":"hr"},"rate":{"type":"number","format":"float","example":100},"minimumDuration":{"type":"integer","example":30},"assignment":{"type":"boolean","example":false},"shift":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Network rates created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Network rates created successfully."},"data":{"properties":{"id":{"type":"string","example":"SP-123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error occurred","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:write","x-fido-module":"settings_rates_billing","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":3}},"/v1/settings/portal/provider/rates-billing/{tab}":{"get":{"tags":["Settings · Rates & Billing"],"summary":"Retrieve paginated assignment rates list with optional filters","description":"**Required scope:** `settings_rates_billing:read`  \n**Roles:** service-provider\n\nFetch a paginated list of assignment rates list entries. Allows filtering, searching, and sorting.","operationId":"ext_get_settings_portal_provider_rates_billing_By_tab","parameters":[{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'rates', 'network_rates')","required":true,"schema":{"type":"string","enum":["rates","network_rates"],"example":"rates"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"search","in":"query","description":"Search keyword","schema":{"type":"string"}},{"name":"columns","in":"query","description":"Comma-separated list of searchable columns","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Column to sort by","schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}},{"name":"perPage","in":"query","description":"Items per page","schema":{"type":"integer"}},{"name":"siteType","in":"query","description":"Filter by site ID","schema":{"type":"string"}},{"name":"serviceType","in":"query","description":"Filter by service ID","schema":{"type":"string"}},{"name":"providerType","in":"query","description":"Filter by service provider ID","schema":{"type":"string"}},{"name":"serviceRate","in":"query","description":"Filter by rate ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rates & billing details retrieved."},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"rateType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"After Hours"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"CART"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Hearing"}},"type":"object"},"certification":{"properties":{"id":{"type":"integer","example":7},"label":{"type":"string","example":"BEI DI"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"remote"},"label":{"type":"string","example":"Remote"}},"type":"object"},"specialization":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"},"unit":{"type":"string","example":"hour","nullable":true},"rate":{"type":"number","example":0},"minimumDuration":{"type":"integer","example":1,"nullable":true},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true},"disabledDelete":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":1}},"type":"object"}},"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."},"errors":{"type":"object","example":{"search":["Invalid search parameter"]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Unknown tab.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"type":"object","example":{"tab":["The selected tab is invalid. Valid options are: rates, network_rates."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected error occurred","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read","x-fido-module":"settings_rates_billing","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":3}},"/v1/settings/portal/provider/{tab}":{"get":{"tags":["Providers"],"summary":"Retrieve specific tab details of a service provider portal","description":"**Required scope:** `providers:read`  \n**Roles:** service-provider\n\nFetches the details for a specific tab within a consumer, based on the provided consumer ID and tab identifier.","operationId":"ext_get_settings_portal_provider_By_tab","parameters":[{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details', 'localizations', 'availability', 'notification','qualifications','requirement_and_preferences')","required":true,"schema":{"type":"string","enum":["details","localizations","availability","notification","qualifications","requirement_and_preferences","rates_billing"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Service provider portal details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Consumer details retrieved!"},"data":{"properties":{"id":{"type":"string","example":"SPR-MD5MK3"},"name":{"type":"string","example":"test"},"description":{"type":"string","example":"I am doing testing"},"email":{"type":"string","example":"user@example.com"},"logo":{"type":"string","example":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg"},"countryCode":{"type":"string","example":"+1"},"phone":{"type":"string","example":"9786159228"},"phoneExtension":{"type":"string","example":"null"},"phoneType":{"type":"string","example":"sms_and_voice"},"videoPhoneCountryCode":{"type":"string","example":"+1"},"videoPhone":{"type":"string","example":"9786159226"},"addressLine1":{"type":"string","example":"123 Bark Street"},"addressLine2":{"type":"string","example":"3434 Street"},"city":{"type":"string","example":"Austin1"},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","example":"33629"},"gender":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"employmentStatus":{"type":"string","example":"contractor"},"hearingStatus":{"type":"string","example":"deaf"},"serviceProviderRole":{"type":"string","example":"individual"},"employmentStartDate":{"type":"string","format":"date-time","example":"2025-08-03 18:30:00"},"employmentEndDate":{"type":"string","nullable":true},"videoPhoneType":{"type":"string","example":"null"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Consumer details retrieved!","data":{"id":"SPR-MD5MK3","name":"test","description":"I am doing testing","email":"user@example.com","logo":"https://d3t50b2fzyr6w1.cloudfront.net/service_providers/SPR-MD5MK3/logo/689492853dac8_Test.jpg","countryCode":"+1","phone":"9786159228","phoneExtension":"null","phoneType":"sms_and_voice","videoPhoneCountryCode":"+1","videoPhone":"9786159226","addressLine1":"123 Bark Street","addressLine2":"3434 Street","city":"Austin1","state":null,"postalCode":"33629","gender":null,"status":null,"employmentStatus":"contractor","hearingStatus":"deaf","serviceProviderRole":"individual","employmentStartDate":"2025-08-03 18:30:00","employmentEndDate":null,"videoPhoneType":"null"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified service provider portal does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified service provider portal does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:read","x-fido-module":"providers","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1},"post":{"tags":["Providers"],"summary":"Update a service provider portal","description":"**Required scope:** `providers:write`  \n**Roles:** service-provider\n\nUpdates a service provider portal by auth user the given payload.","operationId":"ext_post_settings_portal_provider_By_tab","parameters":[{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details', 'notification','qualifications','requirement_and_preferences')","required":true,"schema":{"type":"string","enum":["details","notification","qualifications","requirement_and_preferences"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_001"}}],"requestBody":{"description":"Service Provider update payload","required":true,"content":{"application/json":{"schema":{"required":["email","name"],"properties":{"name":{"type":"string","example":"John"},"email":{"type":"string","format":"email","example":"user@example.com"},"phone":{"type":"string","example":"+1234567890","nullable":true},"isPublished":{"type":"boolean","example":true},"skills":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"proficiency":{"type":"string","example":"advanced"}},"type":"object"}}},"type":"object"}}}},"responses":{"200":{"description":"Service provider updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service provider updated successfully."},"data":{"properties":{"id":{"type":"string","example":"SP-123"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'providers:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed. On the details tab this includes any org-owned setting sent by the provider: status, employmentStatus, enableCustomRates, adminFeeType, adminFee, providerAdminFeeMethod, internalNotes, allowClientsToBroadcastImmediately, assignmentRequest (refused when present, even as null; the last two on the notification tab as well). employmentStartDate, employmentEndDate and serviceProviderRole are ignored rather than refused; the stored values are kept.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Validation failed."},"errors":{"type":"object","example":{"enableCustomRates":"Custom rates are managed by your organization."}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error occurred","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Detailed error message","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"providers:write","x-fido-module":"providers","x-fido-roles":["service-provider"],"x-fido-area":"Provider portal","x-fido-area-rank":1}},"/v1/settings/provider-rates":{"get":{"tags":["Settings · Rates & Billing"],"summary":"List provider rates","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves a paginated list of provider rates with optional filters. Finances data: without Finance Read it answers 200 with an empty page (`data` [], `meta.total` 0) and the reason in `message`, whatever the role holds on Rates & Billing.","operationId":"ext_get_settings_provider_rates","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search term to filter rates by service type, provider type, certification, or specialization","required":false,"schema":{"type":"string","example":"ASL"}},{"name":"startDate","in":"query","description":"Start date for filtering rates (format: YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2023-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering rates (format: YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2023-12-31"}},{"name":"sortBy","in":"query","description":"Field to sort by (e.g., 'rate', 'serviceType', 'providerRole')","required":false,"schema":{"type":"string","example":"rate"}},{"name":"sortOrder","in":"query","description":"Sort order (asc or desc)","required":false,"schema":{"type":"string","example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Provider rates retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"providerRole":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"certification":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"specialization":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"unit":{"type":"string","example":"hour"},"rate":{"type":"integer","example":0},"minimumDuration":{"type":"integer","example":1},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true},"disabledDelete":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"rateType":{"id":1,"label":"Example label"},"serviceType":{"id":1,"label":"Example label"},"serviceProviderType":{"id":1,"label":"Example label"},"providerRole":{"id":"string","label":"Example label"},"certification":{"id":"USR-LBW3CV","label":"Example label"},"siteType":{"id":"string","label":"Example label"},"specialization":{"id":"USR-LBW3CV","label":"Example label"},"unit":"hour","rate":0,"minimumDuration":1,"assignment":true,"shift":true,"disabledDelete":true}],"meta":{"currentPage":1,"lastPage":5,"perPage":10,"total":50}}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider rates","x-fido-area-rank":0},"post":{"tags":["Settings · Rates & Billing"],"summary":"Create provider rates","description":"**Required scope:** `settings_rates_billing:write` and `finance:write`  \n**Roles:** admin, scheduler\n\nCreates provider rates by expanding multi-select fields into individual rows. Same expansion logic as service type rates, plus providerRoles as a free combination field. Duplicates are detected by all fields except rate and minimumDuration.","operationId":"ext_post_settings_provider_rates","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["rate","rateType","serviceProviderType","serviceType","siteType","unit"],"properties":{"serviceType":{"description":"Multi-select service types","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"serviceProviderType":{"description":"Multi-select provider types","type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Hearing Interpreter"}},"type":"object"}},"certification":{"description":"Multi-select certifications","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"NIC"}},"type":"object"},"nullable":true},"rateType":{"description":"Multi-select rate types","type":"array","items":{"properties":{"id":{"type":"integer","example":3},"label":{"type":"string","example":"Emergency"}},"type":"object"}},"siteType":{"description":"Multi-select site types","type":"array","items":{"properties":{"id":{"type":"string","example":"onsite_client"},"label":{"type":"string","example":"On-Site (Client)"}},"type":"object"}},"specialization":{"description":"Multi-select specializations","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"},"nullable":true},"providerRole":{"description":"Multi-select provider roles","type":"array","items":{"properties":{"id":{"type":"string","example":"agency"},"label":{"type":"string","example":"Agency"}},"type":"object"},"nullable":true},"unit":{"type":"string","example":"hr"},"rate":{"type":"number","example":3},"minimumDuration":{"type":"integer","example":34,"nullable":true},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":false}},"type":"object"}}}},"responses":{"201":{"description":"Provider rates created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"12 provider rate(s) saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"12 provider rate(s) saved successfully.","data":null}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved. The message is under errors.unit.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"unit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:write finance:write","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider rates","x-fido-area-rank":0}},"/v1/settings/provider-rates/{provider_rate}":{"delete":{"tags":["Settings · Rates & Billing"],"summary":"Delete provider rate","description":"**Required scope:** `settings_rates_billing:delete` and `finance:delete`  \n**Roles:** admin, scheduler\n\nDeletes the specified provider rate.","operationId":"ext_delete_settings_provider_rates_By_provider_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"provider_rate","in":"path","description":"Unique identifier of the provider rate to delete","required":true,"schema":{"type":"string","example":"3"}}],"responses":{"200":{"description":"Provider rate deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider rate has been deleted successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Provider rate has been deleted successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:delete finance:delete","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider rates","x-fido-area-rank":0},"get":{"tags":["Settings · Rates & Billing"],"summary":"Get provider rate by ID","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves a single provider rate by its ID. Finances data: without Finance Read it answers 200 with an empty page (`data` [], `meta.total` 0) and the reason in `message`, whatever the role holds on Rates & Billing.","operationId":"ext_get_settings_provider_rates_By_provider_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"provider_rate","in":"path","description":"Unique identifier of the provider rate","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Provider rate retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"integer","example":1},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"providerRole":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"certification":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"specialization":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"unit":{"type":"string","example":"hour"},"rate":{"type":"integer","example":0},"minimumDuration":{"type":"integer","example":1},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true},"disabledDelete":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":1,"rateType":{"id":1,"label":"Example label"},"serviceType":{"id":1,"label":"Example label"},"serviceProviderType":{"id":1,"label":"Example label"},"providerRole":{"id":"string","label":"Example label"},"certification":{"id":"USR-LBW3CV","label":"Example label"},"siteType":{"id":"string","label":"Example label"},"specialization":{"id":"USR-LBW3CV","label":"Example label"},"unit":"hour","rate":0,"minimumDuration":1,"assignment":true,"shift":true,"disabledDelete":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Provider rate not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Provider rate not found."}},"type":"object"},"example":{"success":false,"message":"Provider rate not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider rates","x-fido-area-rank":0},"put":{"tags":["Settings · Rates & Billing"],"summary":"Update provider rate","description":"**Required scope:** `settings_rates_billing:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdates an existing provider rate with the specified details.","operationId":"ext_put_settings_provider_rates_By_provider_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"provider_rate","in":"path","description":"Unique identifier of the provider rate to update","required":true,"schema":{"type":"string","example":"3"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"unit":{"type":"string","example":"hr"},"rate":{"type":"number","example":67},"minimumDuration":{"type":"integer","example":89,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Provider rate updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider rate has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Provider rate has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved. The message is under errors.unit.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"unit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:edit finance:edit","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider rates","x-fido-area-rank":0},"patch":{"tags":["Settings · Rates & Billing"],"summary":"Update provider rate","description":"**Required scope:** `settings_rates_billing:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdates an existing provider rate with the specified details.","operationId":"ext_patch_settings_provider_rates_By_provider_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"provider_rate","in":"path","description":"Unique identifier of the provider rate to update","required":true,"schema":{"type":"string","example":"3"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"unit":{"type":"string","example":"hr"},"rate":{"type":"number","example":67},"minimumDuration":{"type":"integer","example":89,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Provider rate updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider rate has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Provider rate has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved. The message is under errors.unit.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"unit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:edit finance:edit","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider rates","x-fido-area-rank":0}},"/v1/settings/rates-billing":{"post":{"tags":["Settings · Rates & Billing"],"summary":"Create or update rate and billing settings","description":"**Required scope:** `settings_rates_billing:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nCreates or updates the rate and billing settings for an organization, including service type rates, provider rates, expense reimbursement settings, client billing cancellations, invoice and pro forma settings.","operationId":"ext_post_settings_rates_billing","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"defaultCurrency":{"type":"string","example":"USD"},"serviceTypeRateSettings":{"type":"array","items":{"properties":{"serviceType":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"ASL"}},"type":"object"},"minimumProviderDurationRules":{"type":"array","items":{"properties":{"value":{"type":"number","example":"3"},"duration":{"type":"string","example":"Hours"},"minProviders":{"type":"integer","example":"2"}},"type":"object"}},"applyCancellationFee":{"type":"boolean","example":true},"feeType":{"type":"string","example":"flat"},"feeValue":{"type":"number","example":"5"},"cancellationWindow":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"12 hours"}},"type":"object"}},"type":"object"}},"serviceTypeRates":{"type":"array","items":{"properties":{"rateType":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"standard"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"string","example":"2"},"label":{"type":"string","example":"Hearing"}},"type":"object"},"certification":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"RID"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"onsite"},"label":{"type":"string","example":"Onsite"}},"type":"object"},"specialization":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Medical"}},"type":"object"},"unit":{"type":"string","example":"per_hour"},"rate":{"type":"number","example":"50.00"},"minimumDuration":{"type":"integer","example":"6"},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true}},"type":"object"}},"singleRates":{"type":"array","items":{"properties":{"serviceType":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"ASL"}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","example":"50.00"},"assignmentRateUnit":{"type":"string","example":"per_hour"},"shiftEnabled":{"type":"boolean","example":true},"shiftRate":{"type":"number","example":"60.00"},"shiftRateUnit":{"type":"string","example":"per_hour"}},"type":"object"}},"providerSingleRates":{"description":"Organization default single PAY rates (provider pay side of singleRates).","type":"array","items":{"properties":{"serviceType":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"string","example":"2"},"label":{"type":"string","example":"Hearing"}},"type":"object"},"assignmentEnabled":{"type":"boolean","example":true},"assignmentRate":{"type":"number","example":"40.00"},"assignmentRateUnit":{"type":"string","example":"hr"},"shiftEnabled":{"type":"boolean","example":true},"shiftRate":{"type":"number","example":"45.00"},"shiftRateUnit":{"type":"string","example":"hr"}},"type":"object"}},"providerRates":{"type":"array","items":{"properties":{"rateType":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"standard"}},"type":"object"},"certification":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"RID"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"onsite"},"label":{"type":"string","example":"Onsite"}},"type":"object"},"specialization":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Medical"}},"type":"object"},"providerRole":{"properties":{"id":{"type":"string","example":"agency"},"label":{"type":"string","example":"Agency"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"ASL"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"string","example":"2"},"label":{"type":"string","example":"Hearing"}},"type":"object"},"unit":{"type":"string","example":"per_hour"},"rate":{"type":"number","example":"50.00"},"minimumDuration":{"type":"integer","example":"6"},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true}},"type":"object"}},"expenseRepressibility":{"type":"string","example":"bill_to_client"},"expensesEnabledForAssignment":{"type":"boolean","example":true},"expensesEnabledForShift":{"type":"boolean","example":true},"expensesEnabledForClient":{"type":"boolean","example":true},"expensesEnabledForClientLocation":{"type":"boolean","example":true},"expensesEnabledForOrganization":{"type":"boolean","example":true},"expensesEnabledForOrganizationLocation":{"type":"boolean","example":true},"expenseSubmissionDeadline":{"type":"integer","example":7},"expenseSubmissionDuration":{"type":"string","example":"days"},"expenseOverrideLateSubmissions":{"type":"boolean","example":true},"expenseApprovalWorkflow":{"type":"string","example":"organization"},"billingCancellations":{"properties":{"expenseRepressibility":{"type":"string","example":"bill_to_client"},"paymentTerm":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Net 30"}},"type":"object"},"billingFrequency":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Monthly"}},"type":"object"},"invoiceFrequency":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Monthly"}},"type":"object"},"invoicesPerCycle":{"type":"integer","example":1},"beginBillingSchedule":{"type":"string","format":"date-time","example":"2023-10-01T00:00:00Z"},"billingDay":{"properties":{"id":{"type":"string","example":"last"},"label":{"type":"string","example":"Last Day"}},"type":"object"},"billingResponsibility":{"type":"string","example":"client"},"enableProFormaStatement":{"type":"boolean","example":true},"proFormaCadence":{"type":"string","example":"monthly"},"defaultBillingDocument":{"type":"string","example":"invoice"},"cancellationWindow":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"12 hours"}},"type":"object"},"cancellationFeeType":{"type":"string","example":"flat"},"cancellationFeeNotes":{"type":"string","example":"Cancellation fee applies if canceled within 12 hours."}},"type":"object"},"invoiceSettings":{"properties":{"taxPercentage":{"type":"number","example":18},"discount":{"type":"number","example":10},"autoGenerate":{"type":"boolean","example":true},"autoSend":{"type":"boolean","example":true},"paymentTerm":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Net 30"}},"type":"object"},"notes":{"type":"string","example":"Thank you for your business!"},"deliveryMethod":{"type":"string","example":"email"},"enableEmailReminder":{"type":"boolean","example":true},"reminderBeforeDueDate":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"3 days before"}},"type":"object"}},"reminderAfterDueDate":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"1 day after"}},"type":"object"}},"internalApproval":{"type":"boolean","example":true},"approvedDeadline":{"type":"integer","example":7},"fallbackBehavior":{"type":"string","example":"auto_approve"},"approvalAboveAmount":{"type":"number","example":1000}},"type":"object"},"proFormaSettings":{"properties":{"enableProFormaStatement":{"type":"boolean","example":true},"autoGenerate":{"type":"boolean","example":true},"autoSend":{"type":"boolean","example":true},"approvalBeforeInvoice":{"type":"boolean","example":true},"notes":{"type":"string","example":"Pro Forma invoice for your review."},"deliveryMethod":{"type":"string","example":"email"},"enableEmailReminder":{"type":"boolean","example":true},"reminderBeforeDueDate":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"3 days before"}},"type":"object"}},"reminderAfterDueDate":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"1 day after"}},"type":"object"}},"internalApprovalBeforeInvoice":{"type":"boolean","example":true},"approvedDeadline":{"type":"integer","example":7},"fallbackBehavior":{"type":"string","example":"auto_approve"},"approvalAboveAmount":{"type":"number","example":1000},"clientApprovalBeforeInvoice":{"type":"boolean","example":true},"notifyClientOnProFormaGenerate":{"type":"boolean","example":true},"clientReminderSchedule":{"type":"string","example":"weekly"},"clientApprovalDeadline":{"type":"integer","example":7},"clientFallbackBehavior":{"type":"string","example":"auto_approve"}},"type":"object"}},"type":"object"}}}},"responses":{"200":{"description":"Settings have been updated.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Settings have been updated"},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Settings have been updated","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. The payload carries a Service Type Rates, Provider Pay or Reimbursable Expenses field (serviceTypeRateSettings, singleRates, providerSingleRates, the expense settings) and the role has no Finance Read, or the role has no Rates & Billing Edit. Nothing is saved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved (a unit sent back exactly as stored is kept, even one saved before units were checked). The message is under the key of the field that carried the unit: serviceTypeRateSettings.N.billingUnit, serviceTypeRateSettings.N.providerPayUnit, singleRates.N.assignmentRateUnit, singleRates.N.shiftRateUnit, providerSingleRates.N.assignmentRateUnit or providerSingleRates.N.shiftRateUnit (N is the row index).","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"error","message":"Unable to save. Please check the highlighted fields.","errors":{"singleRates.0.assignmentRateUnit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:edit finance:edit","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate and billing settings","x-fido-area-rank":4}},"/v1/settings/rates-billing/provider-pay-cancellation":{"get":{"tags":["Settings · Rates & Billing"],"summary":"Retrieve provider pay cancellation settings","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nFetches the provider pay cancellation configuration for the organization, including the cancellation window, fee type, fee value and notes.","operationId":"ext_get_settings_rates_billing_provider_pay_cancellation","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Provider pay cancellation retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider pay cancellation retrieved!"},"data":{"properties":{"allowCancellationPay":{"type":"boolean","example":true},"cancellationWindow":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"feeType":{"type":"string","example":"string"},"feeValue":{"type":"integer","example":0},"cancellationPayNotes":{"type":"string","example":"Added by the scheduler."}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Provider pay cancellation retrieved!","data":{"allowCancellationPay":true,"cancellationWindow":{"id":1,"label":"Example label"},"feeType":"string","feeValue":0,"cancellationPayNotes":"Added by the scheduler."}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Provider portal","x-fido-area-rank":3}},"/v1/settings/rates-billing/sidebar":{"get":{"tags":["Settings · Rates & Billing"],"summary":"Rates and billing sidebar","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nThe data the rates and billing screen's sidebar needs: today, the organization's default currency. A fixed alias of `rates-billing/{tab}` with tab=sidebar.","operationId":"ext_get_settings_rates_billing_sidebar","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Sidebar data retrieved","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Rates & billing details retrieved!"},"data":{"properties":{"defaultCurrency":{"properties":{"id":{"type":"string","example":"USD"},"label":{"type":"string","example":"US Dollar"}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate and billing settings","x-fido-area-rank":4}},"/v1/settings/rates-billing/{tab}":{"get":{"tags":["Settings · Rates & Billing"],"summary":"Retrieve specific tab details of rates and billing settings","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nFetches the details for a specific tab within the rates and billing settings, based on the provided tab identifier. The service-type-rates, provider-pay and expenses-settings tabs are Finances data: without Finance Read they answer 200 with an empty page (`data` [], `meta.total` 0) and the reason in `message`. The other tabs follow Rates & Billing alone.","operationId":"ext_get_settings_rates_billing_By_tab","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'sidebar', 'service-type-rates', 'expenses-settings', 'cancellation-settings', 'invoice-proforma-settings', 'payables-and-payment-settings')","required":true,"schema":{"type":"string","enum":["sidebar","service-type-rates","provider-pay","expenses-settings","cancellation-settings","invoice-proforma-settings","payables-and-payment-settings"],"example":"sidebar"}}],"responses":{"200":{"description":"Rates and billing details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"defaultCurrency":{"type":"string","example":"USD"},"providerRates":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"rateType":{"type":"integer","example":1},"serviceType":{"type":"integer","example":1},"serviceProviderType":{"type":"integer","example":1},"providerRole":{"type":"string","example":"agency"},"certification":{"type":"integer","example":1},"siteType":{"type":"string","example":"onsite"},"specialization":{"type":"integer","example":1},"unit":{"type":"string","example":"per_hour"},"rate":{"type":"string","example":"50.00"},"minimumDuration":{"type":"integer","example":6},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"defaultCurrency":"USD","providerRates":[{"id":1,"rateType":1,"serviceType":1,"serviceProviderType":1,"providerRole":"agency","certification":1,"siteType":"onsite","specialization":1,"unit":"per_hour","rate":"50.00","minimumDuration":6,"assignment":true,"shift":true}]}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Rate and billing settings","x-fido-area-rank":4}},"/v1/settings/reimbursable-expenses":{"get":{"tags":["Settings · Rates & Billing"],"summary":"List reimbursable expenses","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves a paginated list of reimbursable expenses with optional filters. Finances data: without Finance Read it answers 200 with an empty page (`data` [], `meta.total` 0) and the reason in `message`, whatever the role holds on Rates & Billing.","operationId":"ext_get_settings_reimbursable_expenses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search term to filter expenses by name or other attributes","required":false,"schema":{"type":"string","example":"Expense 1"}},{"name":"startDate","in":"query","description":"Start date for filtering expenses (format: YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2023-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering expenses (format: YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2023-12-31"}},{"name":"sortBy","in":"query","description":"Field to sort the results by (e.g., 'name', 'created_at')","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sort order for the results (e.g., 'asc', 'desc')","required":false,"schema":{"type":"string","example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page for pagination","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"List of reimbursable expenses retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"enabled":{"type":"boolean","example":true},"expenseType":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"reimbursementBasis":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"rate":{"type":"integer","example":0},"unit":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"proofRequired":{"type":"boolean","example":true},"contractorEligible":{"type":"boolean","example":true},"networkEligible":{"type":"boolean","example":true},"employedEligible":{"type":"boolean","example":true},"appliedToAssignment":{"type":"boolean","example":true},"appliedToShift":{"type":"boolean","example":true},"travelRadius":{"type":"string","example":"string"},"autoApprovalThreshold":{"type":"integer","example":0},"billTo":{"type":"string","example":"string"},"visibleToProvider":{"type":"boolean","example":true},"visibleToClient":{"type":"boolean","example":true},"expenseCategoryNotes":{"type":"string","example":"Added by the scheduler."},"maximumReimbursementCap":{"type":"string","example":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"name":"Example name","enabled":true,"expenseType":{"id":"string","label":"Example label"},"reimbursementBasis":{"id":"string","label":"Example label"},"rate":0,"unit":{"id":"string","label":"Example label"},"proofRequired":true,"contractorEligible":true,"networkEligible":true,"employedEligible":true,"appliedToAssignment":true,"appliedToShift":true,"travelRadius":"string","autoApprovalThreshold":0,"billTo":"string","visibleToProvider":true,"visibleToClient":true,"expenseCategoryNotes":"Added by the scheduler.","maximumReimbursementCap":"string"}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":2}}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Reimbursable expenses","x-fido-area-rank":1},"post":{"tags":["Settings · Rates & Billing"],"summary":"Create reimbursable expense","description":"**Required scope:** `settings_rates_billing:write` and `finance:write`  \n**Roles:** admin, scheduler\n\nCreates a new reimbursable expense with the specified details.","operationId":"ext_post_settings_reimbursable_expenses","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"One reimbursable expense in the organization's catalog.","required":["name","rate","expenseType","reimbursementBasic","billTo"],"properties":{"name":{"description":"Unique in the catalog.","type":"string","maxLength":255,"example":"Mileage"},"enabled":{"description":"Defaults to true.","type":"boolean","example":true,"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"example":"travel"},"reimbursementBasic":{"description":"How the rate is applied.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"per_unit"},"rate":{"type":"number","example":0.67},"unit":{"description":"Unit the rate is per, such as mile.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billTo":{"description":"client and organization are accepted as aliases. Defaults to the organization's billing setting when that is set.","type":"string","enum":["bill_to_client","organization_pays","client","organization"],"example":"bill_to_client"},"proofRequired":{"description":"Providers must attach a receipt.","type":"boolean","nullable":true},"appliedToAssignment":{"type":"boolean","nullable":true},"appliedToShift":{"type":"boolean","nullable":true},"contractorEligible":{"type":"boolean","nullable":true},"networkEligible":{"type":"boolean","nullable":true},"employedEligible":{"type":"boolean","nullable":true},"visibleToProvider":{"type":"boolean","nullable":true},"visibleToClient":{"type":"boolean","nullable":true},"travelRadius":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"autoApprovalThreshold":{"description":"Amounts up to this approve automatically. Defaults to 0.","type":"number","example":25,"nullable":true},"expenseCategoryNotes":{"type":"string","maxLength":2000,"nullable":true},"maximumReimbursementCap":{"type":"number","example":150,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Reimbursable expense have been updated.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expense has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Expense has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:write finance:write","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Reimbursable expenses","x-fido-area-rank":1}},"/v1/settings/reimbursable-expenses/{reimbursable_expense}":{"delete":{"tags":["Settings · Rates & Billing"],"summary":"Delete reimbursable expense","description":"**Required scope:** `settings_rates_billing:delete` and `finance:delete`  \n**Roles:** admin, scheduler\n\nDeletes the specified reimbursable expense.","operationId":"ext_delete_settings_reimbursable_expenses_By_reimbursable_expense","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"reimbursable_expense","in":"path","description":"Unique identifier of the reimbursable expense to update","required":true,"schema":{"type":"string","example":"3"}}],"responses":{"200":{"description":"Reimbursable expense have been updated.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expense has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Expense has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:delete finance:delete","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Reimbursable expenses","x-fido-area-rank":1},"get":{"tags":["Settings · Rates & Billing"],"summary":"Retrieve a single reimbursable expense (not implemented)","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\n**Not implemented.** The route is registered, but the controller action has no body, so the call succeeds with an empty response and no `{success, message, data}` envelope. Read the reimbursable expense from the list endpoint `/v1/settings/reimbursable-expenses` instead. Finances data: without Finance Read it answers 200 with an empty page (`data` [], `meta.total` 0) and the reason in `message`, whatever the role holds on Rates & Billing.","operationId":"ext_get_settings_reimbursable_expenses_By_reimbursable_expense","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"reimbursable_expense","in":"path","description":"ID of the reimbursable expense.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Empty body — the action is not implemented."},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Reimbursable expenses","x-fido-area-rank":1},"put":{"tags":["Settings · Rates & Billing"],"summary":"Update reimbursable expense","description":"**Required scope:** `settings_rates_billing:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdate a new reimbursable expense with the specified details.","operationId":"ext_put_settings_reimbursable_expenses_By_reimbursable_expense","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"reimbursable_expense","in":"path","description":"Unique identifier of the reimbursable expense to update","required":true,"schema":{"type":"string","example":"3"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Only the fields sent change.","properties":{"name":{"description":"Unique in the catalog.","type":"string","maxLength":255,"example":"Mileage"},"enabled":{"description":"Defaults to true.","type":"boolean","example":true,"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"example":"travel"},"reimbursementBasic":{"description":"How the rate is applied.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"per_unit"},"rate":{"type":"number","example":0.67},"unit":{"description":"Unit the rate is per, such as mile.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billTo":{"description":"client and organization are accepted as aliases. Defaults to the organization's billing setting when that is set.","type":"string","enum":["bill_to_client","organization_pays","client","organization"],"example":"bill_to_client"},"proofRequired":{"description":"Providers must attach a receipt.","type":"boolean","nullable":true},"appliedToAssignment":{"type":"boolean","nullable":true},"appliedToShift":{"type":"boolean","nullable":true},"contractorEligible":{"type":"boolean","nullable":true},"networkEligible":{"type":"boolean","nullable":true},"employedEligible":{"type":"boolean","nullable":true},"visibleToProvider":{"type":"boolean","nullable":true},"visibleToClient":{"type":"boolean","nullable":true},"travelRadius":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"autoApprovalThreshold":{"description":"Amounts up to this approve automatically. Defaults to 0.","type":"number","example":25,"nullable":true},"expenseCategoryNotes":{"type":"string","maxLength":2000,"nullable":true},"maximumReimbursementCap":{"type":"number","example":150,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Reimbursable expense have been updated.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expense has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Expense has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:edit finance:edit","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Reimbursable expenses","x-fido-area-rank":1},"patch":{"tags":["Settings · Rates & Billing"],"summary":"Update reimbursable expense","description":"**Required scope:** `settings_rates_billing:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdate a new reimbursable expense with the specified details.","operationId":"ext_patch_settings_reimbursable_expenses_By_reimbursable_expense","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"reimbursable_expense","in":"path","description":"Unique identifier of the reimbursable expense to update","required":true,"schema":{"type":"string","example":"3"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Only the fields sent change.","properties":{"name":{"description":"Unique in the catalog.","type":"string","maxLength":255,"example":"Mileage"},"enabled":{"description":"Defaults to true.","type":"boolean","example":true,"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"example":"travel"},"reimbursementBasic":{"description":"How the rate is applied.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"per_unit"},"rate":{"type":"number","example":0.67},"unit":{"description":"Unit the rate is per, such as mile.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"billTo":{"description":"client and organization are accepted as aliases. Defaults to the organization's billing setting when that is set.","type":"string","enum":["bill_to_client","organization_pays","client","organization"],"example":"bill_to_client"},"proofRequired":{"description":"Providers must attach a receipt.","type":"boolean","nullable":true},"appliedToAssignment":{"type":"boolean","nullable":true},"appliedToShift":{"type":"boolean","nullable":true},"contractorEligible":{"type":"boolean","nullable":true},"networkEligible":{"type":"boolean","nullable":true},"employedEligible":{"type":"boolean","nullable":true},"visibleToProvider":{"type":"boolean","nullable":true},"visibleToClient":{"type":"boolean","nullable":true},"travelRadius":{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},"nullable":true},"autoApprovalThreshold":{"description":"Amounts up to this approve automatically. Defaults to 0.","type":"number","example":25,"nullable":true},"expenseCategoryNotes":{"type":"string","maxLength":2000,"nullable":true},"maximumReimbursementCap":{"type":"number","example":150,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Reimbursable expense have been updated.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Expense has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Expense has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:edit finance:edit","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Reimbursable expenses","x-fido-area-rank":1}},"/v1/settings/role-event-trigger-notifications":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get all role event trigger notifications","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves all role event trigger notifications with search, filtering, and pagination support","operationId":"ext_get_settings_role_event_trigger_notifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search term to filter notifications by role name","required":false,"schema":{"type":"string","example":"Admin"}},{"name":"startDate","in":"query","description":"Start date for filtering (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2025-12-31"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"roleId":{"type":"integer","example":1},"role":{"properties":{"id":{"type":"integer","example":2},"name":{"type":"string","example":"Admin"},"slug":{"type":"string","example":"admin"}},"type":"object"},"inApp":{"type":"boolean","example":true},"email":{"type":"boolean","example":true},"sms":{"type":"boolean","example":true},"canOverride":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Role event trigger notifications","x-fido-area-rank":4},"post":{"tags":["Settings · Notifications & Preferences"],"summary":"Store or update role event trigger notification","description":"**Required scope:** `settings_notifications_preferences:edit`  \n**Roles:** admin, scheduler\n\nCreates new notification or updates existing one based on role_id. Supports partial updates - only provided fields will be updated.","operationId":"ext_post_settings_role_event_trigger_notifications","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"description":"Single notification object - supports partial updates","required":true,"content":{"application/json":{"schema":{"properties":{"roleId":{"description":"Role ID (required)","type":"integer","example":2},"inApp":{"description":"Enable in-app notifications (optional)","type":"boolean","example":true},"email":{"description":"Enable email notifications (optional)","type":"boolean","example":false},"sms":{"description":"Enable SMS notifications (optional)","type":"boolean","example":true},"canOverride":{"description":"Whether the role can override (optional)","type":"boolean","example":false}},"type":"object"},"example":{"roleId":2,"inApp":true,"email":false,"sms":true,"canOverride":false}}}},"responses":{"200":{"description":"Successful creation/update","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Role event trigger notification updated successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The given data was invalid."},"errors":{"type":"object","example":{"roleId":["The selected roleId is invalid."],"inApp":["The inApp field must be true or false."],"email":["The email field must be true or false."],"sms":["The sms field must be true or false."],"canOverride":["The canOverride field must be true or false."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:edit","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Role event trigger notifications","x-fido-area-rank":4}},"/v1/settings/role-event-trigger-notifications/{id}":{"get":{"tags":["Settings · Notifications & Preferences"],"summary":"Get role event trigger notification by ID","description":"**Required scope:** `settings_notifications_preferences:read`  \n**Roles:** admin, scheduler\n\nRetrieves a specific role event trigger notification by its ID","operationId":"ext_get_settings_role_event_trigger_notifications_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"id","in":"path","description":"Role event trigger notification ID","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Role event trigger notification retrieved successfully."},"data":{"properties":{"id":{"type":"integer","example":1},"roleId":{"type":"integer","example":1},"role":{"properties":{"id":{"type":"integer","example":2},"name":{"type":"string","example":"Admin"},"slug":{"type":"string","example":"admin"}},"type":"object"},"inApp":{"type":"boolean","example":true},"email":{"type":"boolean","example":true},"sms":{"type":"boolean","example":true},"canOverride":{"type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_notifications_preferences:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Role event trigger notification not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Role event trigger notification not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_notifications_preferences:read","x-fido-module":"settings_notifications_preferences","x-fido-roles":["admin","scheduler"],"x-fido-area":"Role event trigger notifications","x-fido-area-rank":4}},"/v1/settings/schedule-exceptions/{id}":{"delete":{"tags":["Settings · General"],"summary":"Delete a organization schedule exceptions list entry","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDeletes a organization schedule exceptions list entry by its ID. If the ID does not exist, a 404 error will be returned.","operationId":"ext_delete_settings_schedule_exceptions_By_id","parameters":[{"name":"id","in":"path","description":"The ID of the service provider vacation list entry to delete","required":true,"schema":{"type":"integer","example":2}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}}],"responses":{"200":{"description":"Deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Vacation deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service provider vacation entry not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Unexpected server error occurred.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Organization details","x-fido-area-rank":11}},"/v1/settings/service-type-rates":{"get":{"tags":["Settings · Rates & Billing"],"summary":"List service type rates","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves a paginated list of service type rates with optional filters. Finances data: without Finance Read it answers 200 with an empty page (`data` [], `meta.total` 0) and the reason in `message`, whatever the role holds on Rates & Billing.","operationId":"ext_get_settings_service_type_rates","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Search term to filter rates by service type, provider type, certification, or specialization","required":false,"schema":{"type":"string","example":"ASL"}},{"name":"startDate","in":"query","description":"Start date for filtering rates (format: YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2023-01-01"}},{"name":"endDate","in":"query","description":"End date for filtering rates (format: YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date","example":"2023-12-31"}},{"name":"siteType","in":"query","description":"Filter by site type (e.g., 'onsite_client', 'onsite_org', 'remote')","required":false,"schema":{"type":"string","example":"onsite_client"}},{"name":"serviceType","in":"query","description":"Filter by service type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"providerType","in":"query","description":"Filter by service provider type ID","required":false,"schema":{"type":"integer","example":2}},{"name":"rateType","in":"query","description":"Filter by rate type ID","required":false,"schema":{"type":"integer","example":1}},{"name":"certification","in":"query","description":"Filter by certification ID","required":false,"schema":{"type":"integer","example":1}},{"name":"specialization","in":"query","description":"Filter by specialization ID","required":false,"schema":{"type":"integer","example":1}},{"name":"sortBy","in":"query","description":"Field to sort by (e.g., 'rate', 'serviceType', 'certification')","required":false,"schema":{"type":"string","example":"rate"}},{"name":"sortOrder","in":"query","description":"Sort order (asc or desc)","required":false,"schema":{"type":"string","example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Service type rates retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"certification":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"specialization":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"unit":{"type":"string","example":"hour"},"rate":{"type":"integer","example":0},"minimumDuration":{"type":"integer","example":1},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true},"disabledDelete":{"type":"boolean","example":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":5},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":50}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"rateType":{"id":1,"label":"Example label"},"serviceType":{"id":1,"label":"Example label"},"serviceProviderType":{"id":1,"label":"Example label"},"certification":{"id":"USR-LBW3CV","label":"Example label"},"siteType":{"id":"string","label":"Example label"},"specialization":{"id":"USR-LBW3CV","label":"Example label"},"unit":"hour","rate":0,"minimumDuration":1,"assignment":true,"shift":true,"disabledDelete":true}],"meta":{"currentPage":1,"lastPage":5,"perPage":10,"total":50}}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service type rates","x-fido-area-rank":2},"post":{"tags":["Settings · Rates & Billing"],"summary":"Create service type rates","description":"**Required scope:** `settings_rates_billing:write` and `finance:write`  \n**Roles:** admin, scheduler\n\nCreates service type rates by expanding multi-select fields into individual rows. Relationship-dependent fields (serviceType → serviceProviderType → certification) must belong together, while free combination fields (rateType × siteType × specialization) produce a cartesian product. Flat fields (assignment, shift, unit, rate, minimumDuration) are copied to every generated row. Duplicates are detected by all dimension fields + unit; if assignment OR shift overlaps, the existing record is updated.","operationId":"ext_post_settings_service_type_rates","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["rate","rateType","serviceProviderType","serviceType","siteType","unit"],"properties":{"serviceType":{"description":"Multi-select service types","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"ASL"}},"type":"object"}},"serviceProviderType":{"description":"Multi-select provider types","type":"array","items":{"properties":{"id":{"type":"integer","example":2},"label":{"type":"string","example":"Hearing Interpreter"}},"type":"object"}},"certification":{"description":"Multi-select certifications","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"NIC"}},"type":"object"},"nullable":true},"rateType":{"description":"Multi-select rate types","type":"array","items":{"properties":{"id":{"type":"integer","example":3},"label":{"type":"string","example":"Emergency"}},"type":"object"}},"siteType":{"description":"Multi-select site types","type":"array","items":{"properties":{"id":{"type":"string","example":"onsite_client"},"label":{"type":"string","example":"On-Site (Client)"}},"type":"object"}},"specialization":{"description":"Multi-select specializations","type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Legal"}},"type":"object"},"nullable":true},"unit":{"type":"string","example":"hr"},"rate":{"type":"number","example":3},"minimumDuration":{"type":"integer","example":34,"nullable":true},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":false}},"type":"object"}}}},"responses":{"201":{"description":"Service type rates created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"8 service type rate(s) saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"8 service type rate(s) saved successfully.","data":null}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved. The message is under errors.unit.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"unit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:write finance:write","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service type rates","x-fido-area-rank":2}},"/v1/settings/service-type-rates/{service_type_rate}":{"delete":{"tags":["Settings · Rates & Billing"],"summary":"Delete service type rate","description":"**Required scope:** `settings_rates_billing:delete` and `finance:delete`  \n**Roles:** admin, scheduler\n\nDeletes the specified service type rate.","operationId":"ext_delete_settings_service_type_rates_By_service_type_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"service_type_rate","in":"path","description":"Unique identifier of the service type rate to delete","required":true,"schema":{"type":"string","example":"3"}}],"responses":{"200":{"description":"Service type rate deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service type rate has been deleted successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Service type rate has been deleted successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:delete finance:delete","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service type rates","x-fido-area-rank":2},"get":{"tags":["Settings · Rates & Billing"],"summary":"Get service type rate by ID","description":"**Required scope:** `settings_rates_billing:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves a single service type rate by its ID. Finances data: without Finance Read it answers 200 with an empty page (`data` [], `meta.total` 0) and the reason in `message`, whatever the role holds on Rates & Billing.","operationId":"ext_get_settings_service_type_rates_By_service_type_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"service_type_rate","in":"path","description":"Unique identifier of the service type rate","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Service type rate retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"integer","example":1},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"certification":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"siteType":{"properties":{"id":{"type":"string","example":"string"},"label":{"type":"string","example":"Example label"}},"type":"object"},"specialization":{"properties":{"id":{"type":"string","example":"USR-LBW3CV"},"label":{"type":"string","example":"Example label"}},"type":"object"},"unit":{"type":"string","example":"hour"},"rate":{"type":"integer","example":0},"minimumDuration":{"type":"integer","example":1},"assignment":{"type":"boolean","example":true},"shift":{"type":"boolean","example":true},"disabledDelete":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":1,"rateType":{"id":1,"label":"Example label"},"serviceType":{"id":1,"label":"Example label"},"serviceProviderType":{"id":1,"label":"Example label"},"certification":{"id":"USR-LBW3CV","label":"Example label"},"siteType":{"id":"string","label":"Example label"},"specialization":{"id":"USR-LBW3CV","label":"Example label"},"unit":"hour","rate":0,"minimumDuration":1,"assignment":true,"shift":true,"disabledDelete":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Service type rate not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Service type rate not found."}},"type":"object"},"example":{"success":false,"message":"Service type rate not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:read finance:read","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service type rates","x-fido-area-rank":2},"put":{"tags":["Settings · Rates & Billing"],"summary":"Update service type rate","description":"**Required scope:** `settings_rates_billing:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdates an existing service type rate with the specified details.","operationId":"ext_put_settings_service_type_rates_By_service_type_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"service_type_rate","in":"path","description":"Unique identifier of the service type rate to update","required":true,"schema":{"type":"string","example":"3"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"unit":{"type":"string","example":"hr"},"rate":{"type":"number","example":67},"minimumDuration":{"type":"integer","example":89,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Service type rate updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service type rate has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Service type rate has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved. The message is under errors.unit.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"unit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:edit finance:edit","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service type rates","x-fido-area-rank":2},"patch":{"tags":["Settings · Rates & Billing"],"summary":"Update service type rate","description":"**Required scope:** `settings_rates_billing:edit` and `finance:edit`  \n**Roles:** admin, scheduler\n\nUpdates an existing service type rate with the specified details.","operationId":"ext_patch_settings_service_type_rates_By_service_type_rate","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"service_type_rate","in":"path","description":"Unique identifier of the service type rate to update","required":true,"schema":{"type":"string","example":"3"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"unit":{"type":"string","example":"hr"},"rate":{"type":"number","example":67},"minimumDuration":{"type":"integer","example":89,"nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Service type rate updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Service type rate has been saved successfully."},"data":{"type":"string","nullable":true}},"type":"object"},"example":{"success":true,"message":"Service type rate has been saved successfully.","data":null}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden. These mappings are Finances data, so a role without Finance Read is refused whatever it holds on Rates & Billing; with it, the Rates & Billing level the change needs decides.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved. The message is under errors.unit.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"array","items":{"type":"object"}}},"type":"object"},"example":{"success":false,"message":"Unable to save. Please check the highlighted fields.","errors":{"unit":["The unit must be Per Hour or Per Minute (hr or min)."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_rates_billing:edit finance:edit","x-fido-module":"settings_rates_billing","x-fido-roles":["admin","scheduler"],"x-fido-area":"Service type rates","x-fido-area-rank":2}},"/v1/settings/update-requirement-field/{id}":{"put":{"tags":["Settings · General"],"summary":"Update a specific field in requirement and preferences","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdates only the fields provided in the request for a requirement and preference entry.","operationId":"ext_put_settings_update_requirement_field_By_id","parameters":[{"name":"id","in":"path","description":"ID of the requirement_and_preference to update","required":true,"schema":{"type":"integer"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID to identify the tenant context","required":true,"schema":{"type":"string","example":"tenant_123"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"skill_id":{"type":"object","example":{"id":3,"label":"Skill 3"}},"specialization_id":{"type":"array","items":{"type":"object","example":{"id":2,"label":"Spec 2"}}}},"type":"object"}}}},"responses":{"200":{"description":"Field(s) updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Requirement updated successfully."},"data":{"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Requirements and preferences","x-fido-area-rank":10}},"/v1/shift-blocks":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve paginated shift blocks with optional filters","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of shift blocks. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_shift_blocks","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"first shift"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"Name","in":"query","description":"Search by name or ID","required":false,"schema":{"type":"string","example":"First Shift"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Shift blocks retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"First Shift"},"description":{"type":"string","example":"Morning Shift."},"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"17:00:00"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shift blocks","x-fido-area-rank":9},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new shift block","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new shift block with a name,description,start time and end time.","operationId":"ext_post_shift_blocks","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["endTime","name","startTime"],"properties":{"name":{"type":"string","example":"First Shift"},"description":{"type":"string","example":"Morning Shift.","nullable":true},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"17:00:00"}},"type":"object"}}}},"responses":{"201":{"description":"Shift block created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift block created!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"First Shift"},"description":{"type":"string","example":"Morning Shift."},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"17:00:00"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Shift block created!","data":{"id":10,"name":"First Shift","description":"Morning Shift.","startTime":"09:00:00","endTime":"17:00:00"}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shift blocks","x-fido-area-rank":9}},"/v1/shift-blocks/{shift_block}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a shift block","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a shift block by its ID.","operationId":"ext_delete_shift_blocks_By_shift_block","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"shift_block","in":"path","description":"ID of the shift block to delete.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Shift block deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift block deleted!"}},"type":"object"},"example":{"success":true,"message":"Shift block deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Shift block not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Shift block with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Shift block with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shift blocks","x-fido-area-rank":9},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a shift block by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a shift block by its ID.","operationId":"ext_get_shift_blocks_By_shift_block","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"shift_block","in":"path","description":"ID of shift block to retrieve.","required":true,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Shift block retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift block retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"description":{"type":"string","example":"Short human-readable description."},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"09:00:00"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Shift block retrieved successfully!","data":{"id":1,"name":"Example name","description":"Short human-readable description.","startTime":"09:00:00","endTime":"09:00:00"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Shift block not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Shift block with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Shift block with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shift blocks","x-fido-area-rank":9},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing shift block","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing shift block by ID.","operationId":"ext_put_shift_blocks_By_shift_block","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"shift_block","in":"path","description":"ID of the shift block to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"First Shift"},"description":{"type":"string","example":"Morning Shift.","nullable":true},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"17:00:00"}},"type":"object"}}}},"responses":{"200":{"description":"Shift block updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift block updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"First Shift"},"description":{"type":"string","example":"Morning Shift."},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"17:00:00"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Shift block updated!","data":{"id":10,"name":"First Shift","description":"Morning Shift.","startTime":"09:00:00","endTime":"17:00:00"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Shift block not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Shift block with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Shift block with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shift blocks","x-fido-area-rank":9},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing shift block","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing shift block by ID.","operationId":"ext_patch_shift_blocks_By_shift_block","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"shift_block","in":"path","description":"ID of the shift block to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"First Shift"},"description":{"type":"string","example":"Morning Shift.","nullable":true},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"17:00:00"}},"type":"object"}}}},"responses":{"200":{"description":"Shift block updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift block updated!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"First Shift"},"description":{"type":"string","example":"Morning Shift."},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endTime":{"type":"string","format":"time","example":"17:00:00"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Shift block updated!","data":{"id":10,"name":"First Shift","description":"Morning Shift.","startTime":"09:00:00","endTime":"17:00:00"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Shift block not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Shift block with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"Shift block with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shift blocks","x-fido-area-rank":9}},"/v1/shift-clients/{id}/no-show":{"delete":{"tags":["Shifts"],"summary":"Reverse a client No Show mark","description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler\n\nClears the No Show flag for a client on a shift — the correction path when the mark was applied by mistake. Restores the client to the served count and to normal billing treatment, and clears any no-show fee entered with the mark.","operationId":"ext_delete_shift_clients_By_id_no_show","parameters":[{"name":"id","in":"path","description":"shift_client row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"reason":{"type":"string","maxLength":1000,"example":"Marked in error — client did attend","nullable":true},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"No Show reversed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"No Show has been removed for this client."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Client is not currently marked as No Show","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":1},"post":{"tags":["Shifts"],"summary":"Mark a client as No Show on a shift","description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler\n\nRecords that a client attached to this shift did not show, without changing the shift status or detaching the client — the booking record stays intact. The client is moved out of the served count and billed the no-show fee instead of the delivered service. An optional per-client fee can be entered with the mark; client no-show money has no policy fallback, so an omitted fee simply bills nothing.","operationId":"ext_post_shift_clients_By_id_no_show","parameters":[{"name":"id","in":"path","description":"shift_client row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["reason"],"properties":{"reason":{"type":"string","maxLength":1000,"example":"Client did not attend the appointment"},"noShowFee":{"type":"number","format":"float","example":75,"nullable":true},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Client marked as No Show","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client has been marked as No Show."},"data":{"properties":{"id":{"type":"string","example":"SFT-ZGJ8T2"},"clientId":{"type":"string","example":"CLT-4HD92K"},"isNoShow":{"type":"boolean","example":true},"noShowReason":{"type":"string","example":"Client did not attend the appointment"},"noShowFee":{"type":"number","format":"float","example":75},"affectedRows":{"type":"integer","example":1},"summary":{"properties":{"attached":{"type":"integer","example":3},"noShow":{"type":"integer","example":1},"served":{"type":"integer","example":2}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error — missing reason, unknown client record, or client already marked","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":1}},"/v1/shift-export/{id}":{"get":{"tags":["Shifts"],"summary":"Export a Single Shift to Excel","description":"**Required scope:** `shifts:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports a single shift to an Excel file for download.","operationId":"ext_get_shift_export_By_id","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"path","description":"Unique identifier of the shift to export.","required":true,"schema":{"type":"string","example":"ASG-45FDX"}}],"responses":{"200":{"description":"Excel file containing shift","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:read","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Export","x-fido-area-rank":3}},"/v1/shift-providers/{id}":{"patch":{"tags":["Shifts"],"summary":"Update provider status for an shift","description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler\n\nUpdates the status of a provider for a specific shift.","operationId":"ext_patch_shift_providers_By_id","parameters":[{"name":"id","in":"path","description":"Unique identifier of the shift","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["status"],"properties":{"status":{"description":"'message' sends a message to the provider instead of changing their status — see subject/message below.","type":"string","enum":["assigned","rebroadcast","resend_details","message","declined","interested","not_interested","canceled","pending","un_assigned"],"example":"assigned"},"subject":{"description":"Required when status is 'message'.","type":"string","maxLength":255,"example":"Update on your shift"},"message":{"description":"Required when status is 'message'.","type":"string","maxLength":5000,"example":"Please confirm your availability."},"reason":{"type":"string","maxLength":1000,"example":"Provider requested time off","nullable":true},"notes":{"type":"string","maxLength":1000,"example":"Internal note for the scheduler","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Provider status updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider status updated successfully"},"data":{"properties":{"id":{"type":"string","example":"ASM-ZGJ8T2"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"type":"object","example":{"providerId":["The selected provider does not exist."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":1}},"/v1/shift-providers/{id}/no-show":{"delete":{"tags":["Shifts"],"summary":"Reverse a provider No Show mark","description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler\n\nClears the No Show flag for a provider on a shift — the correction path when the mark was applied by mistake. Restores the provider to the delivered coverage count and to normal billing treatment. Applies to every booked line the provider holds on this shift.","operationId":"ext_delete_shift_providers_By_id_no_show","parameters":[{"name":"id","in":"path","description":"shift_providers row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"reason":{"type":"string","maxLength":1000,"example":"Marked in error — provider did attend","nullable":true},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"No Show reversed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"No Show has been removed for this provider."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Provider is not currently marked as No Show, or FINANCIAL_CONSENT_REQUIRED when billed docs need affectFinancials","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":1},"post":{"tags":["Shifts"],"summary":"Mark an assigned provider as No Show","description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler\n\nFlags a single provider on a shift as No Show without changing the shift status and without reopening the slot. The provider stays assigned — the booking record is history — so coverage continues to report them under `assigned` with the no-show count alongside. Applies to every booked line the provider holds on this shift. `{id}` is a shift_providers row id; the provider it points at is marked in full.","operationId":"ext_post_shift_providers_By_id_no_show","parameters":[{"name":"id","in":"path","description":"shift_providers row id","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["reason"],"properties":{"reason":{"type":"string","maxLength":1000,"example":"Did not arrive on site"},"affectFinancials":{"description":"Required when a finance document linked to the work item is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the money side effects and syncs the linked documents; false changes the flag only and marks those documents out of sync.","type":"boolean","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Provider marked as No Show","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Provider has been marked as No Show."},"data":{"properties":{"id":{"type":"string","example":"SFT-ZGJ8T2"},"serviceProviderId":{"type":"string","example":"SPR-4HD92K"},"isNoShow":{"type":"boolean","example":true},"noShowReason":{"type":"string","example":"Did not arrive on site"},"affectedRows":{"type":"integer","example":2},"summary":{"properties":{"required":{"type":"integer","example":3},"assigned":{"type":"integer","example":3},"noShow":{"type":"integer","example":1},"delivered":{"type":"integer","example":2}},"type":"object"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized — admin only","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error, unknown provider record, or FINANCIAL_CONSENT_REQUIRED when billed docs need affectFinancials","content":{"application/json":{"schema":{"description":"Two shapes reach this status: the request layer's validation envelope (status, message, errors), and the controller's own business-rule rejection in ApiResponse's envelope (success, message, errors, code).","oneOf":[{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"},{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The request could not be processed."},"errors":{"nullable":true},"code":{"type":"string","example":""}},"type":"object"}]}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"No-shows and provider status","x-fido-area-rank":1}},"/v1/shift-summary/{id}/{tab}":{"get":{"tags":["Shifts"],"summary":"Get Shift Summary Tab Details","description":"**Required scope:** `shifts:read`  \n**Roles:** admin, scheduler\n\nRetrieve shift details for a specific tab (summary, historyLogs, insights) for the given tenant. Without Finance Read the money figures are null: the parent summary's `totalRevenue`, each assigned provider's `estimatedPay` and the insights' `estimatedCost.total`; each provider's `rates` is empty.","operationId":"ext_get_shift_summary_By_id_By_tab","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"Shift ID","required":true,"schema":{"type":"string","example":"ASG-12345"}},{"name":"tab","in":"path","description":"Tab name for which shift details are requested","required":true,"schema":{"type":"string","enum":["summary","historyLogs","insights"],"example":"summary"}},{"name":"search","in":"query","description":"Search the audit log. Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort column (default: created_at). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort direction (default: desc). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"perPage","in":"query","description":"Rows per page (default: 10). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":10}},{"name":"page","in":"query","description":"Page number (default: 1). Applies to the `historyLogs` tab only.","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Shift details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift details retrieved successfully."},"data":{"description":"Shift details depend on the selected tab","type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Shift not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Shift not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:read","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/shift/document/files":{"delete":{"tags":["Shifts"],"summary":"Delete shift files by file IDs","operationId":"ext_delete_shift_document_files","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileIds":{"type":"array","items":{"type":"string"},"example":["FILE-001","FILE-002"]}},"type":"object"}}}},"responses":{"200":{"description":"Files deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Files deleted successfully"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Shift files deletion failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler","x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/shift/export":{"get":{"tags":["Shifts"],"summary":"Export All Shifts to Excel","description":"**Required scope:** `shifts:read`  \n**Roles:** admin, scheduler  \n**Lower rate limit:** this route counts against the exports and reports limit. See [Rate limits](/rate-limits).\n\nExports all shifts to an Excel file for download.","operationId":"ext_get_shift_export","parameters":[{"name":"type","in":"query","description":"Optional output format. `csv` downloads the file as CSV; omitted or `xlsx` keeps the default XLSX.","required":false,"schema":{"type":"string","default":"xlsx","enum":["xlsx","csv"]}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"tenant_123"}},{"name":"id","in":"query","description":"Optional shift ID or comma separated IDs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excel file containing shifts","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"description":"The spreadsheet, streamed as a download.","type":"string","format":"binary"}},"application/json":{"schema":{"description":"Returned instead of the file when the row count is over the synchronous threshold: the export runs in the background and the caller is notified when it is ready.","properties":{"queued":{"type":"boolean","example":true},"export_id":{"description":"Identifies the queued export. The file is delivered through the in-app and email notification; the export-status endpoints are not part of the External API.","type":"integer","example":184},"message":{"type":"string","example":"Exporting 2,500 records. You'll receive an in-app and email notification once your file is ready to download."}},"type":"object"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:read","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-rate-limit":"heavy","x-fido-area":"Export","x-fido-area-rank":3}},"/v1/shift/re-assign":{"post":{"tags":["Shifts"],"summary":"Reassign an shift","description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler\n\nReassigns an shift to a new service provider with optional priority and reason.","operationId":"ext_post_shift_re_assign","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["shiftId"],"properties":{"shiftId":{"type":"string","example":"ASG-LVMXVD"},"newAssignee":{"required":["id"],"properties":{"id":{"type":"string","example":"SPR-JVI5GD"},"label":{"type":"string","example":"Demo User"}},"type":"object"},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"HIGH"}},"type":"object"},"reassignmentReason":{"type":"string","example":"Demo reason","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Shift reassigned successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift reassigned successfully."},"data":{"type":"object","nullable":true}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"Validation failed."},"errors":{"type":"object","example":{"shiftId":["The selected shift does not exist."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","example":"Shift reassignment failed."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"An unexpected error occurred — please try again.","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Reassign","x-fido-area-rank":4}},"/v1/shift/{id}/providers/{serviceType}/{status}":{"get":{"tags":["Shifts"],"summary":"Retrieve shift providers","description":"**Required scope:** `shifts:read`  \n**Roles:** admin, scheduler\n\nFetches the shift providers.","operationId":"ext_get_shift_By_id_providers_By_serviceType_By_status","parameters":[{"name":"id","in":"path","description":"Unique identifier of the shift","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"search","in":"query","description":"Search query to filter provider by name, method","required":false,"schema":{"type":"string","example":"John Doe"}},{"name":"serviceType","in":"path","description":"Identifier for the service type","required":true,"schema":{"type":"integer","example":1}},{"name":"status","in":"path","description":"Status of the shift providers","required":true,"schema":{"type":"string","enum":["assigned","interested","pending","declined"],"example":"assigned"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"locationType","in":"query","description":"Limit to providers on this location type.","required":false,"schema":{"type":"string","enum":["onsite","remote"],"example":"onsite"}},{"name":"page","in":"query","description":"Page number (default: 1).","required":false,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Shift providers retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"method":{"type":"string","example":"string"},"status":{"type":"string","example":"string"},"serviceProviderId":{"type":"string","example":"SPR-FG543C"},"onlineStatus":{"type":"string","example":"online"},"name":{"type":"string","example":"Example name"},"image":{"type":"string","example":"https://cdn.example.com/image.png"},"email":{"type":"string","example":"user@example.com"},"distance":{"type":"integer","example":0},"slotType":{"type":"string","example":"string"},"slotStartTime":{"type":"string","format":"time","example":"09:00:00"},"slotEndTime":{"type":"string","format":"time","example":"09:00:00"},"serviceType":{"type":"string","example":"string"},"serviceProviderType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"startDate":{"type":"string","format":"date","example":"2026-01-15"},"startTime":{"type":"string","format":"time","example":"09:00:00"},"endDate":{"type":"string","format":"date","example":"2026-01-15"},"endTime":{"type":"string","format":"time","example":"09:00:00"},"locationType":{"type":"string","example":"string"},"timezone":{"type":"string","example":"America/New_York"},"verifiedTimeLogs":{"type":"boolean","example":true},"isNoShow":{"type":"boolean","example":true},"noShowReason":{"type":"string","example":"Client requested a change"},"noShowMarkedAt":{"type":"string","format":"date-time","example":"2026-01-15 09:00:00"},"noShowMarkedBy":{"type":"string","example":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":1},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":2}},"type":"object"}},"type":"object"},"example":{"success":true,"data":[{"id":1,"method":"string","status":"string","serviceProviderId":"SPR-FG543C","onlineStatus":"online","name":"Example name","image":"https://cdn.example.com/image.png","email":"user@example.com","distance":0,"slotType":"string","slotStartTime":"09:00:00","slotEndTime":"09:00:00","serviceType":"string","serviceProviderType":{"id":1,"label":"Example label"},"startDate":"2026-01-15","startTime":"09:00:00","endDate":"2026-01-15","endTime":"09:00:00","locationType":"string","timezone":"America/New_York","verifiedTimeLogs":true,"isNoShow":true,"noShowReason":"Client requested a change","noShowMarkedAt":"2026-01-15 09:00:00","noShowMarkedBy":"string"}],"meta":{"currentPage":1,"lastPage":1,"perPage":10,"total":2}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified shift does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified shift does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:read","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/shift/{id}/{tab}":{"get":{"tags":["Shifts"],"summary":"Retrieve specific tab details of a shift","description":"**Required scope:** `shifts:read`  \n**Roles:** admin, scheduler\n\nFetches the details for a specific tab within a shift, based on the provided shift ID and tab identifier.","operationId":"ext_get_shift_By_id_By_tab","parameters":[{"name":"id","in":"path","description":"Unique identifier of the shift","required":true,"schema":{"type":"string","example":"ASM-ZGJ8T2"}},{"name":"tab","in":"path","description":"Identifier for the specific tab to fetch (e.g., 'details','providers','requirementPreferences','documents','sidebar','providerStats')","required":true,"schema":{"type":"string","enum":["details","providers","requirementPreferences","documents","sidebar"],"example":"details"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"responses":{"200":{"description":"Shift details retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"properties":{"id":{"type":"string","example":"ASM-MARH4E"},"title":{"type":"string","example":"Shift Title"}},"type":"object"}},"type":"object"},"example":{"success":true,"data":{"id":"ASM-MARH4E","title":"Shift Title"}}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error - Missing or invalid parameters","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Validation Failed"},"errors":{"properties":{"id":{"type":"array","items":{"type":"string","example":"The specified shift does not exist."}}},"type":"object"}},"type":"object"},"example":{"success":false,"message":"Validation Failed","errors":{"id":["The specified shift does not exist."]}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred. Please try again later."}},"type":"object"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:read","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/shifts/{id}":{"post":{"tags":["Shifts"],"summary":"Update an existing shift","operationId":"ext_post_shifts_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"id","in":"path","description":"ID of the shift to be updated","required":true,"schema":{"type":"string","example":"ASG-SA2IVL"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"A partial update: every field is optional and only what is sent is changed — omitted fields keep their stored value. isPublished=true additionally requires whichever of timezone/assignTo/status/broadcast/assignmentMethod/scheduleType/location the shift doesn't already have a stored value for. Unlike an assignment, changing scheduleType on an existing shift is rejected outright.","properties":{"title":{"type":"string","example":"Weekend overnight coverage","nullable":true},"description":{"type":"string","example":"description of the shift","nullable":true},"isPublished":{"type":"boolean","example":true,"nullable":true},"duration":{"description":"Hours — used when setting location.onsite/remote slot capacity.","type":"number","example":1.5,"nullable":true},"allowPointOfContact":{"description":"Any non-empty value (not just client_poc, unlike the assignment endpoint) triggers auto-filling requestorEmail/requestorPhone from the client's primary location contact.","type":"string","example":"client_poc","nullable":true},"requestorName":{"type":"string","example":"John Doe","nullable":true},"requestorEmail":{"type":"string","format":"email","example":"user@example.com","nullable":true},"requestorPhone":{"type":"string","example":"1234567890","nullable":true},"requestorCountryCode":{"type":"string","example":"+1","nullable":true},"requestorPhoneType":{"type":"string","enum":["sms_and_voice","voice_only"],"example":"sms_and_voice","nullable":true},"requestorPhoneExtension":{"type":"string","example":"123","nullable":true},"assignTo":{"type":"string","enum":["client","organization"],"example":"client","nullable":true},"billTo":{"type":"string","enum":["organization","clients"],"example":"clients","nullable":true},"client":{"description":"A single client. Only takes effect on a shift that currently has at most one client — ignored if assignClients/assignClient is sent in the same payload, or if the shift already has more than one client (use assignClients to change a multi-client roster).","properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object","nullable":true},"assignClients":{"description":"The shift's full client roster. Not validated. Replaces the stored roster: any client left off this list is detached, losing its no-show mark, reason, fee, admin fee and per-client notes even if it was already assigned. assignClient (singular key, same array shape) is accepted as a legacy alias.","type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"label":{"type":"string","example":"Client Name"}},"type":"object"},"nullable":true},"assignClient":{"description":"Legacy alias for assignClients — same shape, same effect.","type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"}},"type":"object"},"nullable":true},"assignClientLocation":{"description":"Not validated.","type":"array","items":{"properties":{"id":{"type":"string","example":"1"}},"type":"object"},"nullable":true},"billingDistribution":{"description":"How the shift's cost is divided across multiple clients. Only meaningful on a multi-client shift.","type":"string","enum":["split_evenly","manual_allocation","individual"],"example":"split_evenly","nullable":true},"clientAllocations":{"description":"Required (with totalServiceCharge) when billingDistribution=manual_allocation — the sum of serviceCharges across entries must equal totalServiceCharge.","type":"array","items":{"properties":{"clientId":{"type":"string","example":"CLT-KBX0Q6"},"serviceCharges":{"type":"number","example":125.5}},"type":"object"},"nullable":true},"totalServiceCharge":{"type":"number","example":251,"nullable":true},"location":{"description":"Required (locationType) when isPublished=true and the shift has no stored location. Changing locationType away from one with assigned providers is rejected.","properties":{"locationType":{"type":"string","enum":["onsite","remote","hybrid"],"example":"onsite"},"billingLocationSource":{"type":"string","enum":["organization","client"],"example":"client","nullable":true},"billingOrganizationLocationId":{"description":"Nested here only — unlike the assignment endpoint, there is no top-level billingOrganizationLocationId fallback for a shift update.","type":"string","example":"1","nullable":true},"billingClientLocationId":{"description":"Nested here only — unlike the assignment endpoint, there is no top-level billingClientLocationId fallback for a shift update.","type":"string","example":"1","nullable":true},"billingOption":{"description":"Defaults to primary. Nested here only for a shift update — there is no top-level billingOption fallback (unlike the assignment endpoint).","type":"string","example":"primary","nullable":true},"onsite":{"properties":{"onSiteType":{"type":"string","enum":["organization","client","manual","ondemand"],"example":"client"},"organizationLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"clientLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"manualLocation":{"properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"manualLocationContact":{"description":"contactPhone is required when neither it nor videoPhone already has a value, unless inLineEdit is sent.","properties":{"contactName":{"type":"string","example":"Jane Roe"},"contactEmail":{"type":"string","format":"email","example":"jane@example.test"},"contactPhone":{"type":"string","example":"1234567890","nullable":true},"contactCountryCode":{"type":"string","example":"+1","nullable":true},"contactPhoneExtension":{"type":"string","example":"123","nullable":true},"videoPhone":{"type":"string","example":"1234567890","nullable":true},"videoPhoneCountryCode":{"type":"string","example":"+1","nullable":true}},"type":"object","nullable":true},"onDemandLocationType":{"type":"string","enum":["organization","client","manual"],"example":"organization","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandOrganizationLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandClientLocationId":{"properties":{"id":{"type":"string","example":"1"}},"type":"object","nullable":true},"onDemandManualLocation":{"properties":{"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"Springfield"},"state":{"properties":{"id":{"type":"integer","example":1}},"type":"object"},"postalCode":{"type":"string","example":"12345"}},"type":"object","nullable":true},"serviceTypes":{"description":"Removing a provider type that already has assigned providers is rejected (see location.onsite.serviceTypeBreakdown).","type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"description":"Reducing totalProviders below the number of providers already assigned to that provider type is rejected; the sum of providerTypeBreakdown.totalProviders must equal totalProviders.","type":"array","items":{"properties":{"serviceTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":2},"providerTypeBreakdown":{"type":"array","items":{"properties":{"serviceProviderTypeId":{"type":"integer","example":1},"totalProviders":{"type":"integer","example":1}},"type":"object"}}},"type":"object"}}},"type":"object","nullable":true},"remote":{"properties":{"remoteType":{"type":"string","enum":["ondemand","scheduled"],"example":"scheduled"},"meetingPlatform":{"type":"string","example":"zoom","nullable":true},"meetingLink":{"type":"string","example":"https://zoom.us/j/123","nullable":true},"meetingPhone":{"type":"string","example":"1234567890","nullable":true},"meetingCountryCode":{"type":"string","example":"+1","nullable":true},"meetingExtension":{"type":"string","example":"123","nullable":true},"accessInstruction":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"onDemandLink":{"type":"string","example":"https://meet.example.test/room","nullable":true},"onDemandAccessInstructions":{"type":"string","example":"Dial in 5 minutes early","nullable":true},"serviceTypes":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1}},"type":"object"}},"serviceTypeBreakdown":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"timezone":{"type":"string","example":"America/New_York","nullable":true},"scheduleType":{"description":"Changing this on an existing shift is rejected outright — unlike an assignment update.","type":"string","enum":["one_time","multi_day","recurring"],"example":"recurring","nullable":true},"oneTime":{"description":"Read only when scheduleType=one_time. Changing dateTimeSlots on a completed/past/canceled shift with no linked finance documents is rejected.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"multiDay":{"description":"Read only when scheduleType=multi_day. Same restriction as oneTime.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"recurring":{"description":"Read only when scheduleType=recurring. Same restriction as oneTime.","properties":{"dateTimeSlots":{"type":"array","items":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"}}},"type":"object","nullable":true},"priority":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Priority Label"}},"type":"object","nullable":true},"status":{"description":"Terminal once in the canceled tree. Away from completed/final/past is restricted to No-Show or Canceled.","properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Status Label"}},"type":"object","nullable":true},"rateType":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Rate Type Label"}},"type":"object","nullable":true},"shiftBlock":{"properties":{"id":{"type":"integer","example":1}},"type":"object","nullable":true},"broadcast":{"description":"May only be set to off on a completed/past/canceled shift.","properties":{"id":{"type":"string","example":"on"},"label":{"type":"string","example":"On"}},"type":"object","nullable":true},"broadcastNotify":{"type":"boolean","example":true,"nullable":true},"broadcastAudience":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"}},"type":"object"},"nullable":true},"userRestricted":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"userPreferred":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-DQRNUV"},"label":{"type":"string","example":"User 1"}},"type":"object"},"nullable":true},"notesToServiceProvider":{"type":"string","example":"Reason for preference if any","nullable":true},"internalNotes":{"type":"string","example":"Internal notes about the shift","nullable":true},"externalNotes":{"type":"string","example":"Notes visible to the client","nullable":true},"allowPartialCoverage":{"type":"boolean","example":true,"nullable":true},"partialDuration":{"description":"Partial coverage windows (required when allowPartialCoverage is true). Omit to keep the shift's existing windows.","type":"array","items":{"properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-01"},"startTime":{"type":"string","example":"09:00"},"endTime":{"type":"string","example":"10:00"}},"type":"object"},"nullable":true},"assignmentMethod":{"type":"string","enum":["direct","accept","interest"],"example":"direct","nullable":true},"enableBroadcastBestMatch":{"type":"boolean","example":true,"nullable":true},"assignProviders":{"description":"Omit to keep the shift's currently assigned providers. Prohibited entirely when isPublished is false.","type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"},"serviceType":{"type":"integer","example":1},"locationType":{"type":"string","enum":["onsite","remote"],"example":"onsite"},"serviceProviderType":{"description":"Provider type the provider fills. Inferred when the service type has only one.","type":"integer","example":2,"nullable":true},"partialReason":{"description":"Why a partly matching provider was assigned anyway.","type":"string","nullable":true},"notAvailableReason":{"description":"Why an unavailable provider was assigned anyway.","type":"string","nullable":true},"visibilityReason":{"description":"How the provider came to be listed. Defaults to partial_match_allowed when partialReason is sent, else full_match.","type":"string","example":"client_selected","nullable":true}},"type":"object"},"nullable":true},"requirementAndPreferences":{"description":"Not validated; saved as the shift's requirements and preferences. Derived from location when omitted and location carries provider-type service types.","type":"array","items":{"properties":{"serviceType":{"type":"integer","example":1},"serviceProviderCertifications":{"description":"Required when serviceType is set.","type":"array","items":{"properties":{"serviceProviderType":{"type":"integer","example":1}},"type":"object"}}},"type":"object"},"nullable":true},"overrideSingleRate":{"type":"boolean","example":true,"nullable":true},"overrideBufferTime":{"type":"boolean","example":true,"nullable":true},"overrideClientPreference":{"type":"boolean","example":true,"nullable":true},"clientPreferences":{"description":"Which of the client's stored requirements and preferences the scheduler overrode on this work item. Each flag set to true means that kind is overridden. Stored as sent.","properties":{"clearance":{"type":"boolean","nullable":true},"skill":{"type":"boolean","nullable":true},"certifications":{"type":"boolean","nullable":true},"specialization":{"type":"boolean","nullable":true},"gender":{"type":"boolean","nullable":true},"restrictedServiceProvider":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"preferredServiceProvider":{"type":"boolean","nullable":true}},"type":"object"},"overrideServiceProviderPreference":{"type":"boolean","example":true,"nullable":true},"serviceProviderPreferences":{"description":"Provider-side rules the scheduler overrode on this work item. Stored as sent.","properties":{"overrideBufferTime":{"type":"boolean","nullable":true},"onSite":{"type":"boolean","nullable":true},"remote":{"type":"boolean","nullable":true},"assignmentLimits":{"type":"boolean","nullable":true},"availability":{"type":"boolean","nullable":true},"locationDistance":{"type":"boolean","nullable":true},"restrictedConsumers":{"type":"boolean","nullable":true},"restrictedClients":{"type":"boolean","nullable":true},"restrictedServiceProviders":{"type":"boolean","nullable":true},"preferredConsumers":{"type":"boolean","nullable":true},"preferredClients":{"type":"boolean","nullable":true},"preferredServiceProviders":{"type":"boolean","nullable":true}},"type":"object"},"requireVerifiedTimeDocumentation":{"type":"boolean","example":false,"nullable":true},"reimbursableExpenses":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Expense 1"}},"type":"object"},"nullable":true},"providerExpenses":{"description":"Provider expenses.","type":"array","items":{"description":"Expenses for one provider on a work item. Only providers currently assigned to the work item are processed.","required":["providerId"],"properties":{"entityId":{"description":"Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved.","type":"string","example":"ASG-SA2IVL","nullable":true},"providerId":{"type":"string","example":"SPR-H6OUI3"},"expenses":{"type":"array","items":{"required":["name"],"properties":{"id":{"description":"Existing expense id to update; omit to create.","type":"integer","example":42,"nullable":true},"name":{"type":"string","example":"Parking"},"amount":{"type":"number","minimum":0.01,"example":12.5,"nullable":true},"expense":{"description":"Unit amount, multiplied by quantity.","type":"number","minimum":0.01,"example":12.5,"nullable":true},"quantity":{"type":"number","minimum":0.01,"example":1,"nullable":true},"billTo":{"type":"string","enum":["organization","client"],"example":"organization","nullable":true},"document":{"description":"Receipt: pdf, jpg, jpeg or png, max 2 MB.","type":"string","format":"binary","nullable":true},"isDefault":{"type":"boolean","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom expense.","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"nullable":true},"expenseType":{"type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"nullable":true},"rate":{"description":"Required when reimbursement_basic is percentage.","type":"number","minimum":0,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from.","properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}},"type":"object"}}},"type":"object"},"nullable":true},"invoiceStatus":{"properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"payStatus":{"properties":{"id":{"type":"string","example":"pending"}},"type":"object","nullable":true},"estimatedCost":{"description":"Client-calculated rate preview. Saving is skipped on a completed/past shift unless the slot time actually changed or finance documents are already linked.","type":"object","nullable":true},"customFields":{"description":"Omitted fields are carried forward from what is already stored, so a partial edit never wipes previously saved custom field values.","type":"object","nullable":true},"externalCustomFields":{"description":"Values for the external custom fields, keyed by field id.","type":"object","nullable":true},"documents":{"type":"array","items":{"properties":{"id":{"description":"Existing document id — omit file when updating an existing document's metadata only.","type":"integer","nullable":true},"file":{"description":"Required unless id is sent.","type":"string","format":"binary"},"fileName":{"type":"string","example":"intake-form.pdf"}},"type":"object"},"nullable":true},"affectFinancials":{"description":"When a no-show finance sync fails, true re-throws the error instead of saving the no-show selection silently.","type":"boolean","nullable":true},"noshowStatusReason":{"description":"Required when status is being set to a No-Show status. Every participant not named here is cleared of their no-show flag. A consumers sub-array is still accepted and processed by the shared no-show helper, but a shift has no consumer relation, so it can never do anything — flagged, not modeled here.","type":"array","items":{"properties":{"clients":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CLT-KBX0Q6"},"noShowFee":{"type":"number","example":50,"nullable":true}},"type":"object"}},"providers":{"type":"array","items":{"properties":{"id":{"type":"string","example":"SPR-H6OUI3"}},"type":"object"}},"reason":{"type":"string","example":"Did not attend"}},"type":"object"},"nullable":true},"cancellationDetails":{"description":"cancellationReason/cancellationCausedBy/billableForCancellation/billCancellationClient/payCancellationProvider are also accepted flat at the top level; the nested value under cancellationDetails wins if both are sent.","properties":{"cancellationReason":{"type":"string","example":"Client requested cancellation"},"cancellationCausedBy":{"description":"Who caused the cancellation, as a label or a {id, label} object.","oneOf":[{"type":"string","example":"client"},{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}]},"cancellationCausedByClient":{"description":"The client or clients responsible, when the cause is a client: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"cancellationCausedByProvider":{"description":"The provider or providers responsible, when the cause is a provider: one {id, label} or a list.","oneOf":[{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"},{"type":"array","items":{"properties":{"id":{"example":1,"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"label":{"type":"string","example":"Example","nullable":true}},"type":"object"}}]},"billableForCancellation":{"type":"boolean","example":true},"billCancellationClient":{"description":"When billableForCancellation is true, at least one of billCancellationClient/payCancellationProvider must also be true.","type":"boolean","example":true},"payCancellationProvider":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}}},"responses":{"200":{"description":"Shift updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"description":"The main message; varies by what changed.","type":"string","example":"Shift updated successfully"},"data":{"properties":{"id":{"type":"string","example":"ASG-SA2IVL"},"messages":{"description":"Secondary notices about the save (e.g. providers that could not be re-attached).","type":"array","items":{"type":"string"}},"workItemFinancialsOutOfSync":{"description":"Present when affectFinancials=false was sent but the change actually affects billed amounts.","type":"boolean","nullable":true},"noShowFinanceSync":{"description":"Present when a no-show selection changed.","type":"object","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Shift updation failed","nullable":true},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:edit","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"description":"**Required scope:** `shifts:edit`  \n**Roles:** admin, scheduler","x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/shifts/{id}/financial-summary":{"get":{"tags":["Shifts"],"summary":"Get financial summary for a shift","description":"**Required scope:** `shifts:read` and `finance:read`  \n**Roles:** admin, scheduler\n\nRetrieves comprehensive financial data including client charges, provider compensation, and profit/loss for a specific shift.","operationId":"ext_get_shifts_By_id_financial_summary","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"Shift ID (SFT-XXX)","required":true,"schema":{"type":"string"}},{"name":"clientsPage","in":"query","description":"Page of the clients breakdown (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"clientsPerPage","in":"query","description":"Rows per page of the clients breakdown, 1 to 100.","required":false,"schema":{"type":"integer","example":10}},{"name":"providersPage","in":"query","description":"Page of the providers breakdown (default: 1).","required":false,"schema":{"type":"integer","example":1}},{"name":"providersPerPage","in":"query","description":"Rows per page of the providers breakdown, 1 to 100.","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Financial summary retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Financial summary retrieved successfully"},"data":{"properties":{"clientChargesSummary":{"properties":{"description":{"type":"string","example":"Short human-readable description."},"clients":{"type":"array","items":{"type":"object"}},"totalBilledToClients":{"type":"number","format":"float","example":120.5}},"type":"object"},"providerCompensationSummary":{"properties":{"description":{"type":"string","example":"Short human-readable description."},"providers":{"type":"array","items":{"type":"object"}},"totalProviderPayouts":{"type":"number","format":"float","example":120.5}},"type":"object"},"financialOutcome":{"properties":{"totalRevenue":{"type":"number","format":"float","example":120.5},"totalProviderPayouts":{"type":"number","format":"float","example":120.5},"netProfitLoss":{"type":"number","format":"float","example":120.5}},"type":"object"},"linkedFinanceDocuments":{"properties":{"active":{"type":"object"},"historical":{"type":"object"}},"type":"object"},"providerNoShowFinance":{"type":"object"},"missingActiveInvoice":{"type":"boolean","example":true},"missingActivePayable":{"type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Unauthorized - User does not have permission to view financial data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Shift not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The requested resource could not be found."},"errors":{"description":"Details when the handler has them — a field-keyed object, a single string, or null.","nullable":true},"code":{"description":"Empty unless the handler sets one.","type":"string","example":""}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:read finance:read","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/shifts/{shift}":{"delete":{"tags":["Shifts"],"summary":"Delete an shift","description":"**Required scope:** `shifts:delete`  \n**Roles:** admin, scheduler\n\nDeletes an shift by ID for the given tenant, including child shifts and associated files from S3.","operationId":"ext_delete_shifts_By_shift","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification.","required":true,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"shift","in":"path","description":"ID of the shift to delete","required":true,"schema":{"type":"string","example":"ASG-12345"}}],"responses":{"200":{"description":"Shift deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Shift deleted successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'shifts:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Shift not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Shift not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"shifts:delete","x-fido-module":"shifts","x-fido-roles":["admin","scheduler"],"x-fido-area":"Shifts","x-fido-area-rank":0}},"/v1/skills":{"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve paginated skills with optional filters","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of skills. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_skills","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"communication"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name,skillName)","required":false,"schema":{"type":"string","example":"name,skillName"}},{"name":"skillName","in":"query","description":"Search by skill name or ID","required":false,"schema":{"type":"string","example":"Skill A"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Skills retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Skills","x-fido-area-rank":10},"post":{"tags":["Settings · Service Setup"],"summary":"Create a new skill","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new skill with a name and optional tenant ID.","operationId":"ext_post_skills","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"New Skill"},"tenant_id":{"type":"string","example":"demotenant"}},"type":"object"}}}},"responses":{"201":{"description":"Skill created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Skill created!"},"data":{"properties":{"id":{"type":"integer","example":10},"name":{"type":"string","example":"New Skill"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Skill created!","data":{"id":10,"name":"New Skill","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Skills","x-fido-area-rank":10}},"/v1/skills/{skill}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a skill","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a skill by its ID.","operationId":"ext_delete_skills_By_skill","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"skill","in":"path","description":"ID of the skill to delete.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"200":{"description":"Skill deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Skill deleted!"}},"type":"object"},"example":{"success":true,"message":"Skill deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Skill not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Skill with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Skill with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Skills","x-fido-area-rank":10},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a skill by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a skill by its ID.","operationId":"ext_get_skills_By_skill","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"skill","in":"path","description":"ID of the skill to retrieve.","required":true,"schema":{"type":"integer","example":3}}],"responses":{"200":{"description":"Skill retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Skill retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Skill retrieved successfully!","data":{"id":1,"name":{"id":1,"label":"Example label"}}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Skill not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Skill with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Skill with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Skills","x-fido-area-rank":10},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing skill","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing skill by ID.","operationId":"ext_put_skills_By_skill","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"skill","in":"path","description":"ID of the skill to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Skill"}},"type":"object"}}}},"responses":{"200":{"description":"Skill updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Skill updated!"},"data":{"properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"Updated Skill"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Skill updated!","data":{"id":5,"name":"Updated Skill","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Skill not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Skill with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Skill with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Skills","x-fido-area-rank":10},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing skill","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing skill by ID.","operationId":"ext_patch_skills_By_skill","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"skill","in":"path","description":"ID of the skill to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Updated Skill"}},"type":"object"}}}},"responses":{"200":{"description":"Skill updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Skill updated!"},"data":{"properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"Updated Skill"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Skill updated!","data":{"id":5,"name":"Updated Skill","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Skill not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Skill with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Skill with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Skills","x-fido-area-rank":10}},"/v1/specializations":{"get":{"tags":["Settings · Service Setup"],"summary":"List Specializations with filtering, pagination, and sorting","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nRetrieve a paginated list of specializations, optionally filtered by tenant ID, search term, or name. Supports sorting and pagination.","operationId":"ext_get_specializations","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID (used for multi-tenant filtering)","required":true,"schema":{"type":"string","example":"demoTenant"}},{"name":"search","in":"query","description":"Search keyword for specialization name","required":false,"schema":{"type":"string","example":"Interpreter"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to return","required":false,"schema":{"type":"string","example":"id,name,isCustom"}},{"name":"specializationName","in":"query","description":"Exact specialization name to filter by","required":false,"schema":{"type":"string","example":"ASL Interpretation"}},{"name":"sortBy","in":"query","description":"Column to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order: asc or desc","required":false,"schema":{"type":"string","example":"asc"}},{"name":"perPage","in":"query","description":"Number of records per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Specializations retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"serviceBody":{"type":"integer","example":1,"nullable":true},"serviceBodyName":{"type":"string","example":"Example name","nullable":true},"requirement":{"type":"string","example":"preferred","nullable":true},"notes":{"type":"string","example":"Added by the scheduler.","nullable":true}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":27}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid input or arguments","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid tenant ID provided."},"errors":{"type":"object","example":{"tenantId":["The tenant ID is invalid."]}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Specializations","x-fido-area-rank":11},"post":{"tags":["Settings · Service Setup"],"summary":"Create one or more specializations","description":"**Required scope:** `settings_service_setup:write`  \n**Roles:** admin, scheduler\n\nCreate a new set of specializations with optional service body, requirement, and notes flag. Supports custom or predefined entries.","operationId":"ext_post_specializations","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","requirement"],"properties":{"serviceBody":{"required":["label"],"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"Interpreter Services Board"}},"type":"object"},"name":{"type":"array","items":{"required":["label"],"properties":{"id":{"type":"integer","example":null},"label":{"type":"string","example":"DOJ Clearance"}},"type":"object"},"minItems":1},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"preferred"},"notes":{"type":"string","example":"example notes"}},"type":"object"}}}},"responses":{"201":{"description":"Specializations created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Specializations created!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":12},"name":{"type":"string","example":"DOJ Clearance"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"name":["Specialization name is required."],"serviceBody":["Service Body is required."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}}],"x-fido-scope":"settings_service_setup:write","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Specializations","x-fido-area-rank":11}},"/v1/specializations/{specialization}":{"delete":{"tags":["Settings · Service Setup"],"summary":"Delete a specialization","description":"**Required scope:** `settings_service_setup:delete`  \n**Roles:** admin, scheduler\n\nDelete a specialization by its ID.","operationId":"ext_delete_specializations_By_specialization","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"specialization","in":"path","description":"ID of the specialization to delete.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"200":{"description":"Specialization deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Specialization deleted!"}},"type":"object"},"example":{"success":true,"message":"Specialization deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Specialization not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Specialization with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Specialization with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:delete","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Specializations","x-fido-area-rank":11},"get":{"tags":["Settings · Service Setup"],"summary":"Retrieve a specialization by ID","description":"**Required scope:** `settings_service_setup:read`  \n**Roles:** admin, scheduler\n\nFetch a single specialization by its ID.","operationId":"ext_get_specializations_By_specialization","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"specialization","in":"path","description":"ID of the specialization to retrieve.","required":true,"schema":{"type":"integer","example":5}}],"responses":{"200":{"description":"Specialization retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Specialization retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object"},"serviceBody":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"}},"type":"object","nullable":true},"requirement":{"type":"string","example":"preferred","nullable":true},"notes":{"type":"string","example":"Added by the scheduler.","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Specialization not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Specialization with ID 5 not found."}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:read","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Specializations","x-fido-area-rank":11},"put":{"tags":["Settings · Service Setup"],"summary":"Update an existing specialization","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing specialization by ID with optional service body, requirement, and notes.","operationId":"ext_put_specializations_By_specialization","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"specialization","in":"path","description":"ID of the specialization to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Example Updated"},"serviceBody":{"required":["label"],"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"sdsad"}},"type":"object"},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"preferred"},"notes":{"type":"string","example":"ABC"}},"type":"object"}}}},"responses":{"200":{"description":"Specialization updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Specialization updated!"},"data":{"properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"Example Updated"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Specialization not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Specialization with ID 5 not found."}},"type":"object"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"name":["The name field is required."],"serviceBody.label":["The service body label has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Specializations","x-fido-area-rank":11},"patch":{"tags":["Settings · Service Setup"],"summary":"Update an existing specialization","description":"**Required scope:** `settings_service_setup:edit`  \n**Roles:** admin, scheduler\n\nUpdate an existing specialization by ID with optional service body, requirement, and notes.","operationId":"ext_patch_specializations_By_specialization","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"description":"Organization tenant ID. Required for org and user tier keys.","schema":{"type":"string","example":"TNT-AB12CD34"}},{"name":"specialization","in":"path","description":"ID of the specialization to update.","required":true,"schema":{"type":"integer","example":5}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Example Updated"},"serviceBody":{"required":["label"],"properties":{"id":{"type":"integer","example":null,"nullable":true},"label":{"type":"string","example":"sdsad"}},"type":"object"},"requirement":{"type":"string","enum":["required","preferred","optional"],"example":"preferred"},"notes":{"type":"string","example":"ABC"}},"type":"object"}}}},"responses":{"200":{"description":"Specialization updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Specialization updated!"},"data":{"properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"Example Updated"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_service_setup:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Specialization not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Specialization with ID 5 not found."}},"type":"object"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields."},"errors":{"type":"object","example":{"name":["The name field is required."],"serviceBody.label":["The service body label has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_service_setup:edit","x-fido-module":"settings_service_setup","x-fido-roles":["admin","scheduler"],"x-fido-area":"Specializations","x-fido-area-rank":11}},"/v1/status":{"get":{"tags":["Settings · General"],"summary":"Retrieve all statuses or filter by tenant ID","description":"**Required scope:** `settings_general:read`\n\nFetch a list of all statuses or filter by a specific tenant ID if provided.","operationId":"ext_get_status","parameters":[{"name":"tenantId","in":"query","description":"Tenant ID. Used for multi-tenant filtering.","required":false,"schema":{"type":"string","example":"demotenant"}}],"responses":{"200":{"description":"Statuses retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Status Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Status Retrieved!","data":[{"id":1,"value":1,"label":"Example label","isCustom":true}]}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"status":"error","message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"status":"error","message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Statuses","x-fido-area-rank":4},"post":{"tags":["Settings · General"],"summary":"Create a new status","description":"**Required scope:** `settings_general:write`\n\nCreate a new status with a name and optional tenant ID.","operationId":"ext_post_status","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","tenant_id"],"properties":{"name":{"type":"string","example":"New Status"},"tenant_id":{"type":"string","example":"demotenant"}},"type":"object"}}}},"responses":{"201":{"description":"Status created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Status created!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Status created!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"status":"error","message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"status":"error","message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"parameters":[],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Statuses","x-fido-area-rank":4}},"/v1/status/{id}/{label}":{"delete":{"tags":["Settings · General"],"summary":"Delete a status","description":"**Required scope:** `settings_general:delete`  \n**Roles:** super-admin, admin, scheduler\n\nDelete a status by its ID.","operationId":"ext_delete_status_By_id_By_label","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":6}},{"name":"label","in":"path","description":"Label of the status to delete.","required":true,"schema":{"type":"string","example":"status"}}],"responses":{"200":{"description":"Status deleted successfully.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"success"},"message":{"type":"string","example":"Status deleted!"}},"type":"object"},"example":{"status":"success","message":"Status deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Status not found.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Status with ID 6 not found."}},"type":"object"},"example":{"status":"error","message":"Status with ID 6 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"status":"error","message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["super-admin","admin","scheduler"],"x-fido-area":"Statuses","x-fido-area-rank":4}},"/v1/status/{status}":{"delete":{"tags":["Settings · General"],"summary":"Delete a status by id alone (always 422)","description":"**Required scope:** `settings_general:delete`\n\n**Use `/v1/status/{id}/{label}` instead.** This id-only form is registered by the resource route, but the handler identifies the record from a `label` path segment this route does not carry, so the call always fails validation with `label` required.","operationId":"ext_delete_status_By_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"status","in":"path","description":"ID of the status.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed: the status type could not be resolved from the URL.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The label field is required."}},"type":"object"},"example":{"status":"error","message":"The label field is required."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Statuses","x-fido-area-rank":4},"get":{"tags":["Settings · General"],"summary":"Retrieve a single status (not implemented)","description":"**Required scope:** `settings_general:read`\n\n**Not implemented.** The route is registered, but the controller action has no body, so the call succeeds with an empty response and no `{success, message, data}` envelope. Read the status from the list endpoint `/v1/status` instead.","operationId":"ext_get_status_By_status","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":false,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"status","in":"path","description":"ID of the status.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Empty body — the action is not implemented."},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Statuses","x-fido-area-rank":4},"put":{"tags":["Settings · General"],"summary":"Update an existing status","description":"**Required scope:** `settings_general:edit`\n\nUpdate a status by ID.","operationId":"ext_put_status_By_status","parameters":[{"name":"status","in":"path","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Status"}},"type":"object"}}}},"responses":{"200":{"description":"Status updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Status updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Status updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Status not found.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Status with ID 3 not found."}},"type":"object"},"example":{"status":"error","message":"Status with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"status":"error","message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Statuses","x-fido-area-rank":4},"patch":{"tags":["Settings · General"],"summary":"Update an existing status","description":"**Required scope:** `settings_general:edit`\n\nUpdate a status by ID.","operationId":"ext_patch_status_By_status","parameters":[{"name":"status","in":"path","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Status"}},"type":"object"}}}},"responses":{"200":{"description":"Status updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Status updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Status updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Status not found.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Status with ID 3 not found."}},"type":"object"},"example":{"status":"error","message":"Status with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"status":"error","message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":[],"x-fido-area":"Statuses","x-fido-area-rank":4}},"/v1/tags":{"get":{"tags":["Settings · General"],"summary":"Retrieve all Tags or filter by tenant ID","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a list of all Tags or filter by a specific tenant ID if provided.","operationId":"ext_get_tags","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"tenantId","in":"query","description":"Tenant ID. Used for multi-tenant filtering.","required":false,"schema":{"type":"string","example":"demotenant"}}],"responses":{"200":{"description":"Tags retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Tags Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Tags Retrieved!","data":[{"id":1,"value":1,"label":"Example label","isCustom":true}]}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Tags","x-fido-area-rank":8},"post":{"tags":["Settings · General"],"summary":"Create a new tag","description":"**Required scope:** `settings_general:write`  \n**Roles:** admin, scheduler\n\nCreate a new tag with a name and optional tenant ID.","operationId":"ext_post_tags","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","tenant_id"],"properties":{"name":{"type":"string","example":"Tech tag"},"tenant_id":{"type":"string","example":"demotenant"}},"type":"object"}}}},"responses":{"201":{"description":"tag created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"tag created!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"tag created!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Tags","x-fido-area-rank":8}},"/v1/tags/{id}/{label}":{"delete":{"tags":["Settings · General"],"summary":"Delete  tag","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete tag by its ID.","operationId":"ext_delete_tags_By_id_By_label","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"path","description":"ID of the tag to delete.","required":true,"schema":{"type":"integer","example":7}},{"name":"label","in":"path","description":"Label of the tag to delete.","required":true,"schema":{"type":"string","example":"tag"}}],"responses":{"200":{"description":"Tag deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Tag deleted!"}},"type":"object"},"example":{"success":true,"message":"Tag deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Tag not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Tag with ID 7 not found."}},"type":"object"},"example":{"success":false,"message":"Tag with ID 7 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Tags","x-fido-area-rank":8}},"/v1/tags/{tag}":{"delete":{"tags":["Settings · General"],"summary":"Delete a tag by id alone (always 422)","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\n**Use `/v1/tags/{id}/{label}` instead.** This id-only form is registered by the resource route, but the handler identifies the record from a `label` path segment this route does not carry, so the call always fails validation with `label` required.","operationId":"ext_delete_tags_By_tag","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":"TNT-6SH5MSOU"}},{"name":"tag","in":"path","description":"ID of the tag.","required":true,"schema":{"type":"integer","example":7}}],"responses":{"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation failed: the tag type could not be resolved from the URL.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"The label field is required."}},"type":"object"},"example":{"status":"error","message":"The label field is required."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Tags","x-fido-area-rank":8},"put":{"tags":["Settings · General"],"summary":"Update an tag","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate an tag by ID.","operationId":"ext_put_tags_By_tag","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"tag","in":"path","description":"ID of the tag to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Tech Tag"}},"type":"object"}}}},"responses":{"200":{"description":"Tag updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Tag updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Tag updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Tag not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Tag with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Tag with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Tags","x-fido-area-rank":8},"patch":{"tags":["Settings · General"],"summary":"Update an tag","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate an tag by ID.","operationId":"ext_patch_tags_By_tag","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID. Used for multi-tenant authentication.","required":true,"schema":{"type":"string","example":""}},{"name":"tag","in":"path","description":"ID of the tag to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name"],"properties":{"name":{"type":"string","example":"Updated Tech Tag"}},"type":"object"}}}},"responses":{"200":{"description":"Tag updated successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Tag updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"value":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"isCustom":{"type":"boolean","example":true}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Tag updated!","data":{"id":1,"value":1,"label":"Example label","isCustom":true}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Tag not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Tag with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Tag with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Tags","x-fido-area-rank":8}},"/v1/timezones":{"get":{"tags":["Settings · General"],"summary":"Retrieve paginated timezones with optional filters","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a paginated list of timezones. Allows filtering by name, search, and sorting. Supports multi-tenancy via X-TENANT-ID header.","operationId":"ext_get_timezones","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"search term"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name,timezoneName)","required":false,"schema":{"type":"string","example":"name,value"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Timezones retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"label":{"type":"string","example":"Example label"},"value":{"type":"string"}},"type":"object"}},"meta":{"properties":{"currentPage":{"type":"integer","example":1},"lastPage":{"type":"integer","example":3},"perPage":{"type":"integer","example":10},"total":{"type":"integer","example":30}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Timezones","x-fido-area-rank":12},"post":{"tags":["Settings · General"],"summary":"Create a new timezone","description":"**Required scope:** `settings_general:write`  \n**Roles:** admin, scheduler\n\nCreate a new timezone with a name and value.","operationId":"ext_post_timezones","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["name","value"],"properties":{"name":{"type":"string","example":"New Timezone"},"value":{"type":"string","example":"America/New_York"}},"type":"object"}}}},"responses":{"201":{"description":"Timezone created successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Timezone created successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"New Timezone"},"value":{"type":"string","example":"America/New_York"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid argument provided.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to create timezone."}},"type":"object"},"example":{"success":false,"message":"Failed to create timezone."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Timezones","x-fido-area-rank":12}},"/v1/timezones/{timezone}":{"delete":{"tags":["Settings · General"],"summary":"Delete a timezone","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete a timezone by its ID.","operationId":"ext_delete_timezones_By_timezone","parameters":[{"name":"timezone","in":"path","description":"ID of the timezone to delete","required":true,"schema":{"type":"integer","example":1}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}}],"responses":{"200":{"description":"Timezone deleted successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Timezone deleted successfully!"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Timezone not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Timezone with ID 1 not found."}},"type":"object"},"example":{"success":false,"message":"Timezone with ID 1 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Timezones","x-fido-area-rank":12}},"/v1/travel-radius":{"get":{"tags":["Settings · General"],"summary":"Retrieve all travel radii","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a list of all travel radii.","operationId":"ext_get_travel_radius","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"search","in":"query","description":"Global search term across selected columns","required":false,"schema":{"type":"string","example":"completed"}},{"name":"columns","in":"query","description":"Comma-separated list of columns to search (e.g., name)","required":false,"schema":{"type":"string","example":"name"}},{"name":"Name","in":"query","description":"Search by name or ID","required":false,"schema":{"type":"string","example":"Completed"}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","example":"name"}},{"name":"sortOrder","in":"query","description":"Sorting order (asc or desc)","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"asc"}},{"name":"perPage","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","example":10}}],"responses":{"200":{"description":"Travel Radius retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Travel Radii Retrieved!"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"minDistance":{"type":"string","example":"string"},"maxDistance":{"type":"string","example":"string"},"unit":{"type":"string","example":"hour"}},"type":"object"}}},"type":"object"},"example":{"success":true,"message":"Travel Radii Retrieved!","data":[{"id":1,"name":"Example name","minDistance":"string","maxDistance":"string","unit":"hour"}]}}}},"400":{"description":"Invalid argument provided","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to retrieve."}},"type":"object"},"example":{"success":false,"message":"Failed to retrieve."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Travel radius","x-fido-area-rank":9},"post":{"tags":["Settings · General"],"summary":"Create a new travel radius","description":"**Required scope:** `settings_general:write`  \n**Roles:** admin, scheduler\n\nCreate a new travel radius with a name , minDistance,maxDistance,unit.","operationId":"ext_post_travel_radius","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["maxDistance","minDistance","name","unit"],"properties":{"name":{"type":"string","example":"Up to 300 miles"},"minDistance":{"type":"integer","example":1},"maxDistance":{"type":"integer","example":300},"unit":{"type":"string","example":"Miles"}},"type":"object"}}}},"responses":{"201":{"description":"Travel Radius created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Travel Radius created!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"minDistance":{"type":"string","example":"string"},"maxDistance":{"type":"string","example":"string"},"unit":{"type":"string","example":"hour"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Travel Radius created!","data":{"id":1,"name":"Example name","minDistance":"string","maxDistance":"string","unit":"hour"}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"The name field is required."}},"type":"object"},"example":{"success":false,"message":"The name field is required."}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:write","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Travel radius","x-fido-area-rank":9}},"/v1/travel-radius/{travel_radiu}":{"delete":{"tags":["Settings · General"],"summary":"Delete a travel radius","description":"**Required scope:** `settings_general:delete`  \n**Roles:** admin, scheduler\n\nDelete a travel radius by ID.","operationId":"ext_delete_travel_radius_By_travel_radiu","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"travel_radiu","in":"path","description":"ID of the travel radius to delete.","required":true,"schema":{"type":"integer","example":5}}],"responses":{"200":{"description":"Travel Radius deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Travel Radius deleted!"}},"type":"object"},"example":{"success":true,"message":"Travel Radius deleted!"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:delete' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Travel Radius not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Travel Radius with ID 5 not found."}},"type":"object"},"example":{"success":false,"message":"Travel Radius with ID 5 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:delete","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Travel radius","x-fido-area-rank":9},"get":{"tags":["Settings · General"],"summary":"Retrieve a travel radius by ID","description":"**Required scope:** `settings_general:read`  \n**Roles:** admin, scheduler\n\nFetch a travel radius by its ID.","operationId":"ext_get_travel_radius_By_travel_radiu","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant context","required":true,"schema":{"type":"string","example":"demotenant"}},{"name":"travel_radiu","in":"path","description":"ID of travel radius to retrieve.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Travel radius retrieved successfully.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Travel radius retrieved successfully!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"minDistance":{"type":"string","example":"string"},"maxDistance":{"type":"string","example":"string"},"unit":{"type":"string","example":"hour"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Travel radius retrieved successfully!","data":{"id":1,"name":"Example name","minDistance":"string","maxDistance":"string","unit":"hour"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Travel radius not found.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"travel radius with ID 10 not found."}},"type":"object"},"example":{"success":false,"message":"travel radius with ID 10 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:read","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Travel radius","x-fido-area-rank":9},"put":{"tags":["Settings · General"],"summary":"Update a travel radius","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate a travel radius by ID.","operationId":"ext_put_travel_radius_By_travel_radiu","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"travel_radiu","in":"path","description":"ID of the travel radius to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Up to 40 miles"},"minDistance":{"type":"integer","example":1},"maxDistance":{"type":"integer","example":40},"unit":{"type":"string","example":"Miles"}},"type":"object"}}}},"responses":{"200":{"description":"Travel Radius updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Travel Radius updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"minDistance":{"type":"string","example":"string"},"maxDistance":{"type":"string","example":"string"},"unit":{"type":"string","example":"hour"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Travel Radius updated!","data":{"id":1,"name":"Example name","minDistance":"string","maxDistance":"string","unit":"hour"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Travel Radius not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Travel Radius with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Travel Radius with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Travel radius","x-fido-area-rank":9},"patch":{"tags":["Settings · General"],"summary":"Update a travel radius","description":"**Required scope:** `settings_general:edit`  \n**Roles:** admin, scheduler\n\nUpdate a travel radius by ID.","operationId":"ext_patch_travel_radius_By_travel_radiu","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-6SH5MHOU"}},{"name":"travel_radiu","in":"path","description":"ID of the travel radius to update.","required":true,"schema":{"type":"integer","example":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","example":"Up to 40 miles"},"minDistance":{"type":"integer","example":1},"maxDistance":{"type":"integer","example":40},"unit":{"type":"string","example":"Miles"}},"type":"object"}}}},"responses":{"200":{"description":"Travel Radius updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Travel Radius updated!"},"data":{"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Example name"},"minDistance":{"type":"string","example":"string"},"maxDistance":{"type":"string","example":"string"},"unit":{"type":"string","example":"hour"}},"type":"object"}},"type":"object"},"example":{"success":true,"message":"Travel Radius updated!","data":{"id":1,"name":"Example name","minDistance":"string","maxDistance":"string","unit":"hour"}}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'settings_general:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"Travel Radius not found","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Travel Radius with ID 3 not found."}},"type":"object"},"example":{"success":false,"message":"Travel Radius with ID 3 not found."}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"}},"type":"object"},"example":{"success":false,"message":"Something went wrong!"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"settings_general:edit","x-fido-module":"settings_general","x-fido-roles":["admin","scheduler"],"x-fido-area":"Travel radius","x-fido-area-rank":9}},"/v1/user-roles":{"get":{"tags":["Team"],"summary":"Fetch all roles","description":"**Required scope:** `team:read`\n\nFetches all available roles with their ID, label, value, and slug.","operationId":"ext_get_user_roles","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-NRLWQEDM"}}],"responses":{"200":{"description":"Roles fetched successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Roles fetched successfully"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"1"},"label":{"type":"string","example":"Client"},"value":{"type":"string","example":"1"},"slug":{"type":"string","example":"client"}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Something went wrong","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Error Fetching Roles: ...","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:read","x-fido-module":"team","x-fido-roles":[],"x-fido-area":"Roles and users","x-fido-area-rank":1}},"/v1/users/by-role":{"get":{"tags":["Team"],"summary":"Fetch users by specific roles","description":"**Required scope:** `team:read`\n\nFetches users with roles like Consumer, Client, or Service Provider based on provided slug(s).","operationId":"ext_get_users_by_role","parameters":[{"name":"slug","in":"query","description":"Role slugs to filter by (e.g., service-provider, client, consumer)","required":false,"schema":{"type":"string"}},{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":true,"schema":{"type":"string","example":"TNT-NRLWQEDM"}}],"responses":{"200":{"description":"Users Fetched Successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Users Fetched Successfully"},"data":{"type":"array","items":{"properties":{"id":{"type":"string","example":"CSM-5W5RVY"},"label":{"type":"string","example":"ABC"},"value":{"type":"string","example":"CSM-5W5RVY"},"role":{"type":"string","example":"Consumer"}},"type":"object"}}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Scope, tenant, IP allow-list or RBAC check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:read' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Something went wrong","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Something went wrong!"},"errors":{"description":"Null in production. The exception message only when the application runs with debug on.","type":"string","example":"Error Fetching Users List: ...","nullable":true}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:read","x-fido-module":"team","x-fido-roles":[],"x-fido-area":"Roles and users","x-fido-area-rank":1}},"/v1/users/{id}/resend-invite":{"post":{"tags":["Team"],"summary":"Resend a user's onboarding invite","description":"**Required scope:** `team:write`  \n**Roles:** admin, scheduler\n\nIssues a new set-password link and invalidates the previous one. Limited to one resend per user per five minutes. An admin's invite can be resent only by another admin, and only until it is accepted (no password set and never signed in); super-admin accounts are never targets.","operationId":"ext_post_users_By_id_resend_invite","parameters":[{"name":"X-Tenant-ID","in":"header","description":"Tenant ID for multi-tenant identification","required":false,"schema":{"type":"string","example":"TNT-KHGQXMD6"}},{"name":"id","in":"path","description":"Tenant user ID","required":true,"schema":{"type":"string","example":"USR-5RSWGE"}}],"responses":{"200":{"description":"Invite resent","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invite resent."},"data":{"properties":{"inviteState":{"type":"string","example":"invited"},"inviteExpiresAt":{"type":"string","format":"date-time","example":"2026-01-15 09:00:00"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Invites cannot be resent for this type of account, or the caller may not resend to an admin","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'team:write' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"404":{"description":"No account found for the provided user","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"No account found for the provided user."},"errors":{"example":null,"nullable":true},"code":{"type":"string","example":""}},"type":"object"}}}},"409":{"description":"Account has already set a password, or is an admin who has already signed in (including with SSO)","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"This account has already set a password."},"errors":{"example":null,"nullable":true},"code":{"type":"string","example":""}},"type":"object"}}}},"422":{"description":"Account has no login of its own","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"This account has no login of its own."},"errors":{"example":null,"nullable":true},"code":{"type":"string","example":""}},"type":"object"}}}},"429":{"description":"Resent too recently","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}}},"security":[{"apiKey":[]}],"x-fido-scope":"team:write","x-fido-module":"team","x-fido-roles":["admin","scheduler"],"x-fido-area":"Roles and users","x-fido-area-rank":1}},"/v1/{type}/notes/{id}":{"patch":{"tags":["Assignments"],"summary":"Update notes on an assignment or shift","description":"**Required scope:** `assignments:edit`  \n**Roles:** admin, client, scheduler, consumer\n\nClient/consumer: updates the note to the provider, internal notes and external notes on their own link to the assignment or shift. Admin/scheduler: updates those notes on the assignment or shift itself.","operationId":"ext_patch_By_type_notes_By_id","parameters":[{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string","example":"TNT-588TFV9U"}},{"name":"type","in":"path","description":"Work item type","required":true,"schema":{"type":"string","enum":["assignment","shift"],"example":"assignment"}},{"name":"id","in":"path","description":"Assignment or shift ID","required":true,"schema":{"type":"string","example":"ASG-J5A17Q"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"notesToServiceProvider":{"type":"string","example":"Please arrive 10 minutes early.","nullable":true},"internalNotes":{"type":"string","example":"Internal reference only.","nullable":true},"externalNotes":{"type":"string","example":"Visible to all parties.","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Notes updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Assignment notes updated successfully."}},"type":"object"}}}},"401":{"description":"Missing, invalid or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["API_KEY_MISSING","API_KEY_INVALID","API_KEY_EXPIRED"],"example":"API_KEY_MISSING"}}}}}},"403":{"description":"Forbidden - user does not have access to this assignment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You don't have permission to access this endpoint. This API key is missing the 'assignments:edit' scope."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Always empty on this status.","example":""}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation failures use their own envelope — status rather than success, and no code.","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Unable to save. Please check the highlighted fields"},"errors":{"description":"Field name to its messages. Nested keys are collapsed onto the field the form renders.","type":"object","example":{"name":["Please enter a name."],"email":["The email has already been taken."]}}},"type":"object"}}}},"429":{"description":"Rate limit exceeded. See Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds."},"errors":{"nullable":true,"example":null,"description":"Null on this status."},"code":{"type":"string","description":"Machine-readable reason, for branching on in client code.","enum":["RATE_LIMITED"],"example":"RATE_LIMITED"}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An unexpected error occurred — please try again."},"errors":{"description":"Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.","type":"string","example":null,"nullable":true},"code":{"description":"Always empty: the server-error response carries no error code.","type":"string","example":""}},"type":"object"}}}}},"security":[{"apiKey":[]}],"x-fido-scope":"assignments:edit","x-fido-module":"assignments","x-fido-roles":["admin","client","scheduler","consumer"],"x-fido-area":"Assignments","x-fido-area-rank":0}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"External API key."}},"schemas":{"ProviderPortalExpenseRow":{"description":"One expense line. Name it one of three ways: reimbursableExpenseId (a template line on the work item); sourceReimbursableExpense or categoryId plus customName/name (a custom line seeded from a catalog category); or customName/name alone (a freeform custom line, which needs expense or amount). reimbursableExpenseId and a source category together are refused.","required":["assignmentId","serviceProviderId"],"properties":{"id":{"description":"Existing provider expense id to update; omit to create. A row with id 'reimbursable-basic' (the read-only aggregate row of the provider view) is dropped.","type":"integer","example":42,"nullable":true},"assignmentId":{"description":"Work item id, ASG-* or SFT-*. The first row's prefix decides whether every row is checked against assignments or shifts.","type":"string","example":"ASG-23RT45"},"serviceProviderId":{"description":"Must be an existing service provider id. The first row's value must be the caller's own id.","type":"string","example":"SPR-ABC123"},"reimbursableExpenseId":{"description":"Catalog expense id of a template line attached to the work item","type":"integer","example":7,"nullable":true},"sourceReimbursableExpense":{"description":"Catalog category a custom line is seeded from. May also be sent as a JSON string (multipart). The legacy flat sourceReimbursableExpenseId is not accepted.","properties":{"id":{"type":"integer","example":7},"label":{"type":"string","example":"Mileage","nullable":true}},"type":"object","nullable":true},"categoryId":{"description":"Bare alternative to sourceReimbursableExpense.id","type":"integer","example":7,"nullable":true},"customName":{"type":"string","minLength":1,"example":"Parking","nullable":true},"name":{"description":"Accepted in place of customName","type":"string","minLength":1,"example":"Parking","nullable":true},"isDefault":{"description":"Used with name to resolve whether a name means a template line or a custom one","type":"boolean","example":false,"nullable":true},"expenseType":{"description":"Classification of a freeform custom line","type":"string","enum":["travel","lodging","meals","supplies","miscellaneous"],"example":"travel","nullable":true},"reimbursement_basic":{"description":"Reimbursement basis of a freeform custom line; defaults to flat_amount when only expenseType is sent","type":"string","enum":["per_unit","per_day","flat_amount","percentage"],"example":"flat_amount","nullable":true},"rate":{"description":"Rate for a freeform custom line's basis","type":"number","format":"float","example":0.67,"nullable":true},"unit":{"description":"Unit for a per_unit freeform custom line","type":"string","example":"mile","nullable":true},"maximumReimbursementCap":{"description":"Cap for a freeform custom line","type":"number","format":"float","example":100,"nullable":true},"expense":{"description":"Reimbursement payout; overrides the calculated amount","type":"number","format":"float","minimum":0.01,"example":25.5,"nullable":true},"amount":{"description":"Submitted cost (the receipt amount), which percentage categories calculate from","type":"number","format":"float","minimum":0.01,"example":40,"nullable":true},"quantity":{"description":"Units for per_unit / per_day lines","type":"number","format":"float","minimum":0.01,"example":12,"nullable":true},"billTo":{"description":"Who the line is billed to; an existing line keeps its own when this is omitted","type":"string","enum":["organization","client"],"example":"client","nullable":true},"status":{"description":"Only pending is accepted; omit to keep an existing line's status","type":"string","enum":["pending"],"example":"pending"},"uploadReceipt":{"description":"Receipt file (multipart). Some catalog categories require one.","type":"string","format":"binary","nullable":true},"document":{"description":"Alternative receipt field (multipart): pdf, jpg, jpeg or png, at most 2 MB","type":"string","format":"binary","nullable":true}},"type":"object"},"AssignmentDateTimeSlot":{"description":"One coverage window. recurrenceOption/scheduleDays only apply when the enclosing scheduleType is recurring.","properties":{"startDate":{"type":"string","format":"date","example":"2024-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-04"},"timeSlots":{"type":"array","items":{"properties":{"startTime":{"type":"string","example":"10:00"},"endTime":{"type":"string","example":"12:00"}},"type":"object"}},"scheduleFrequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"example":"daily","nullable":true},"scheduleInterval":{"type":"integer","example":2,"nullable":true},"scheduleDays":{"description":"Days of week this slot recurs on, when scheduleFrequency=weekly.","type":"array","items":{"type":"string","example":"monday"},"nullable":true},"recurrenceOption":{"description":"How the recurrence ends — e.g. an end date or an occurrence count.","type":"string","example":"on_date","nullable":true}},"type":"object"},"PayableOverrideAuditEntry":{"properties":{"previous_value":{"description":"Payable OpenAPI component schemas (per-entity pay calculation).","type":"number","format":"float","nullable":true},"new_value":{"type":"number","format":"float","nullable":true},"reason":{"type":"string","nullable":true},"overridden_by":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"overridden_at":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"PayableRateLine":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"},"PayableRateBreakdownSummary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"PayableRateBreakdown":{"properties":{"base_rate":{"type":"number","format":"float","example":45},"base_hours":{"type":"number","format":"float","example":8},"rules_applied":{"type":"array","items":{"type":"object"}},"rate_lines":{"type":"array","items":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}},"summary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"effective_pay_rate":{"type":"number","format":"float","example":46.67},"total_service_charge":{"type":"number","format":"float","example":360},"source":{"description":"Which time basis priced the lines — not where the rate came from; see rate_source.","type":"string","enum":["check_in","estimated_pay"]},"rate_source":{"description":"Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"description":"Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.","type":"string","example":"Provider Pay Rate","nullable":true},"rate_source_description":{"type":"string","example":"Driven by this provider's own custom pay rate configuration.","nullable":true},"rate_source_is_mixed":{"description":"True when the lines were priced from more than one rate configuration.","type":"boolean","example":false},"rate_configuration":{"description":"Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows.","properties":{"source":{"description":"Null when the work item was priced from more than one configuration.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"label":{"type":"string","example":"Default Pay Rate","nullable":true},"description":{"type":"string","example":"Driven by the organization default provider pay rate configuration.","nullable":true},"is_mixed":{"type":"boolean","example":false},"rows":{"type":"array","items":{"properties":{"service_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"service_provider_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"rate_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"site_type":{"type":"string","example":"onsite_client","nullable":true},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","enum":["hr","min"],"example":"hr"},"source":{"type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}}},"type":"object","nullable":true}},"type":"object"},"PayableBillableEntityLinkageInput":{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"}},"type":"object"},"PayableBillableEntityLinkageOutput":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"is_deleted":{"type":"boolean","example":false}},"type":"object"},"PayableBillableEntityPayCalcInput":{"required":["type","id"],"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"type":"string","enum":["scheduled_time","actual_worked_time","scheduled_actual_fallback"],"nullable":true},"hours_used_for_pay":{"type":"number","format":"float","example":4,"nullable":true},"pay_rate":{"type":"number","format":"float","example":65,"nullable":true},"services_charge":{"type":"number","format":"float","example":260,"nullable":true},"hours_override_reason":{"type":"string","minLength":3,"nullable":true},"pay_rate_override_reason":{"type":"string","minLength":3,"nullable":true}},"type":"object"},"PayableBillableEntityPayCalcOutput":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"isCustom":{"type":"boolean","example":false}},"type":"object","nullable":true},"derived_hours_used_for_pay":{"type":"number","format":"float","nullable":true},"hours_used_for_pay":{"type":"number","format":"float","nullable":true},"is_hours_overridden":{"type":"boolean","example":false},"derived_pay_rate":{"type":"number","format":"float","nullable":true},"pay_rate":{"type":"number","format":"float","nullable":true},"is_pay_rate_overridden":{"type":"boolean","example":false},"services_charge":{"type":"number","format":"float","nullable":true},"pay_rate_breakdown":{"properties":{"base_rate":{"type":"number","format":"float","example":45},"base_hours":{"type":"number","format":"float","example":8},"rules_applied":{"type":"array","items":{"type":"object"}},"rate_lines":{"type":"array","items":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}},"summary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"effective_pay_rate":{"type":"number","format":"float","example":46.67},"total_service_charge":{"type":"number","format":"float","example":360},"source":{"description":"Which time basis priced the lines — not where the rate came from; see rate_source.","type":"string","enum":["check_in","estimated_pay"]},"rate_source":{"description":"Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"description":"Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.","type":"string","example":"Provider Pay Rate","nullable":true},"rate_source_description":{"type":"string","example":"Driven by this provider's own custom pay rate configuration.","nullable":true},"rate_source_is_mixed":{"description":"True when the lines were priced from more than one rate configuration.","type":"boolean","example":false},"rate_configuration":{"description":"Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows.","properties":{"source":{"description":"Null when the work item was priced from more than one configuration.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"label":{"type":"string","example":"Default Pay Rate","nullable":true},"description":{"type":"string","example":"Driven by the organization default provider pay rate configuration.","nullable":true},"is_mixed":{"type":"boolean","example":false},"rows":{"type":"array","items":{"properties":{"service_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"service_provider_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"rate_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"site_type":{"type":"string","example":"onsite_client","nullable":true},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","enum":["hr","min"],"example":"hr"},"source":{"type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"rate_rules_suppressed":{"type":"boolean","example":false},"hours_override_reason":{"description":"Latest hours override reason (mirrors save input when is_hours_overridden).","type":"string","nullable":true},"pay_rate_override_reason":{"description":"Latest pay rate override reason (mirrors save input when is_pay_rate_overridden).","type":"string","nullable":true}},"type":"object"},"PayableEntityPayMetrics":{"properties":{"type":{"type":"string","enum":["assignment","shift"],"example":"assignment"},"id":{"type":"string","example":"ASG-M3PCU1"},"pay_time_basis":{"type":"string","example":"scheduled_actual_fallback"},"derived_hours_used_for_pay":{"type":"number","format":"float","example":8},"hours_used_for_pay":{"type":"number","format":"float","example":8},"is_hours_overridden":{"type":"boolean","example":false},"derived_pay_rate":{"type":"number","format":"float","example":45},"pay_rate":{"type":"number","format":"float","example":45},"is_pay_rate_overridden":{"type":"boolean","example":false},"services_charge":{"type":"number","format":"float","example":260},"pay_rate_breakdown":{"properties":{"base_rate":{"type":"number","format":"float","example":45},"base_hours":{"type":"number","format":"float","example":8},"rules_applied":{"type":"array","items":{"type":"object"}},"rate_lines":{"type":"array","items":{"properties":{"label":{"type":"string","example":"Standard"},"hours":{"type":"number","format":"float","example":6},"rate":{"type":"number","format":"float","example":45},"cost":{"type":"number","format":"float","example":270},"billable_amount":{"description":"What this row actually pays. Equals `cost` on AP rows, where cancellation pay is a per-unit rate.","type":"number","format":"float","example":270},"time_slot":{"type":"string","example":""},"unit":{"type":"string","enum":["hour","minute"],"example":"hour"},"line_type":{"type":"string","enum":["base","surcharge"],"example":"base"},"check_in_id":{"type":"string","nullable":true},"charge_source":{"type":"string","example":"estimated_pay"},"rate_source":{"description":"Which rate configuration this line's rate came from. Null when the line predates rate-source stamping and the work item has no stamped pay rows.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}},"summary":{"properties":{"total_hours":{"type":"number","format":"float","example":8},"total_service_charge":{"type":"number","format":"float","example":382.5},"effective_pay_rate":{"type":"number","format":"float","example":47.81},"line_count":{"type":"integer","example":2}},"type":"object"},"effective_pay_rate":{"type":"number","format":"float","example":46.67},"total_service_charge":{"type":"number","format":"float","example":360},"source":{"description":"Which time basis priced the lines — not where the rate came from; see rate_source.","type":"string","enum":["check_in","estimated_pay"]},"rate_source":{"description":"Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"example":"provider_rate","nullable":true},"rate_source_label":{"description":"Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.","type":"string","example":"Provider Pay Rate","nullable":true},"rate_source_description":{"type":"string","example":"Driven by this provider's own custom pay rate configuration.","nullable":true},"rate_source_is_mixed":{"description":"True when the lines were priced from more than one rate configuration.","type":"boolean","example":false},"rate_configuration":{"description":"Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows.","properties":{"source":{"description":"Null when the work item was priced from more than one configuration.","type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"label":{"type":"string","example":"Default Pay Rate","nullable":true},"description":{"type":"string","example":"Driven by the organization default provider pay rate configuration.","nullable":true},"is_mixed":{"type":"boolean","example":false},"rows":{"type":"array","items":{"properties":{"service_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"service_provider_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"rate_type":{"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}},"type":"object"},"site_type":{"type":"string","example":"onsite_client","nullable":true},"rate":{"type":"number","format":"float","example":45},"unit":{"type":"string","enum":["hr","min"],"example":"hr"},"source":{"type":"string","enum":["provider_rate","default_rate","fallback_rate"],"nullable":true},"source_label":{"type":"string","example":"Provider Pay Rate","nullable":true}},"type":"object"}}},"type":"object","nullable":true}},"type":"object","nullable":true},"rate_rules_suppressed":{"type":"boolean","example":false},"warning_message":{"type":"string","nullable":true},"hours_override_reason":{"type":"string","nullable":true},"pay_rate_override_reason":{"type":"string","nullable":true}},"type":"object"},"FinancePaidOverrideFields":{"description":"Paid or accepted override fields on a full or inline save. override_reason must be an {id, label} object; a bare string is rejected. override_reason_text is required only when id=other.","properties":{"override_locks":{"description":"Edit a paid or accepted document past its locks.","type":"boolean","example":true},"override_reason":{"required":["id","label"],"properties":{"id":{"type":"string","enum":["correction","reversal","reconciliation","other"],"example":"reconciliation"},"label":{"type":"string","example":"Reconciliation"}},"type":"object"},"override_reason_text":{"type":"string","maxLength":1000,"minLength":3,"example":"Corrected line after client call","nullable":true},"override_delivery":{"type":"string","enum":["internal_only","send_updated"],"example":"internal_only"}},"type":"object"},"FinanceResendPromptFields":{"description":"Resend prompt fields on a full or inline save when sensitive unlocked fields change on a sent document. Retry the save with confirmation and resend_delivery.","properties":{"confirmation":{"description":"Confirms the resend prompt.","type":"boolean","example":true},"resend_delivery":{"description":"Canonical: send_updated | internal_only. Legacy aliases send_now | save_only still accepted.","type":"string","enum":["send_updated","internal_only","send_now","save_only"],"example":"internal_only"}},"type":"object"},"GuardianLookup":{"description":"A guardian found by email, before any link exists: the person and their own login, no link fields.","properties":{"id":{"type":"string","example":"GRD-ABC123"},"name":{"type":"string","example":"Jane Doe"},"email":{"type":"string","example":"jane@example.com","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phone":{"type":"string","example":"5551230000","nullable":true},"hasPortalAccess":{"description":"Whether this person already signs in","type":"boolean","example":false},"inviteState":{"type":"string","nullable":true},"inviteExpiresAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"Guardian":{"description":"A guardian as linked to one consumer: the person, the link (relationship, primary, notifications, portal access to this consumer) and the state of the guardian's own login.","properties":{"id":{"type":"string","example":"GRD-ABC123"},"name":{"type":"string","example":"Jane Doe"},"email":{"type":"string","example":"jane@example.com","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phone":{"type":"string","example":"5551230000","nullable":true},"relationshipId":{"description":"Entry from GET /api/v1/guardian-relationships","type":"integer","example":1,"nullable":true},"relationship":{"description":"That entry's name; archived entries still resolve","type":"string","example":"Parent","nullable":true},"isPrimary":{"type":"boolean","example":true},"receivesNotifications":{"type":"boolean","example":true},"hasPortalAccess":{"description":"The login is enabled AND this link grants access to this consumer","type":"boolean","example":false},"inviteState":{"description":"Null when the guardian has no login","type":"string","nullable":true},"inviteExpiresAt":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"DashboardDistributionEntry":{"description":"One slice of a distribution donut: a labelled bucket and its count.","properties":{"label":{"type":"string","example":"Clients (Single Location)"},"count":{"type":"integer","example":12},"type":{"description":"Machine-readable key. Absent on the client-portal location distribution.","type":"string","example":"single_location"}},"type":"object"},"DashboardClientBucket":{"description":"Client counts for one status filter. Every allowed client type is present, including those with a count of zero.","properties":{"summary":{"properties":{"totalClients":{"type":"integer","example":20},"active":{"type":"integer","example":19},"inactive":{"type":"integer","example":1}},"type":"object"},"distribution":{"type":"array","items":{"description":"One slice of a distribution donut: a labelled bucket and its count.","properties":{"label":{"type":"string","example":"Clients (Single Location)"},"count":{"type":"integer","example":12},"type":{"description":"Machine-readable key. Absent on the client-portal location distribution.","type":"string","example":"single_location"}},"type":"object"}}},"type":"object"},"DashboardConsumerBucket":{"description":"Consumer counts for one status filter. Every hearing status is present, zero included, and so is Network. The entries partition the population -- a network consumer is reported under Network and not again under its hearing status -- so the counts add up to totalConsumers.","properties":{"summary":{"properties":{"totalConsumers":{"type":"integer","example":22},"active":{"type":"integer","example":21},"inactive":{"type":"integer","example":1}},"type":"object"},"distribution":{"type":"array","items":{"description":"One slice of a distribution donut: a labelled bucket and its count.","properties":{"label":{"type":"string","example":"Clients (Single Location)"},"count":{"type":"integer","example":12},"type":{"description":"Machine-readable key. Absent on the client-portal location distribution.","type":"string","example":"single_location"}},"type":"object"}},"network":{"description":"Consumers shared through the network, counted within this status filter. Included in totalConsumers exactly once.","type":"integer","example":6}},"type":"object"},"DashboardServiceProviderBucket":{"description":"Provider counts for one service-location filter. This is a modality split, not a status split. Staff/Contractors/Agency cover the tenant's own providers and Network the shared ones, with no provider in two entries, so the distribution adds up to totalProviders.","properties":{"summary":{"properties":{"totalProviders":{"type":"integer","example":17},"active":{"type":"integer","example":17},"inactive":{"type":"integer","example":0},"availablePercentage":{"type":"integer","example":76},"notAvailablePercentage":{"type":"integer","example":24}},"type":"object"},"distribution":{"type":"array","items":{"description":"One slice of a distribution donut: a labelled bucket and its count.","properties":{"label":{"type":"string","example":"Clients (Single Location)"},"count":{"type":"integer","example":12},"type":{"description":"Machine-readable key. Absent on the client-portal location distribution.","type":"string","example":"single_location"}},"type":"object"}}},"type":"object"},"RolePermissionCell":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, `write` and `delete` on Settings → Assignments & Shifts, and `write`, `edit` and `delete` on Schedule, History & Logs and Settings → Invoices; centrally, `portalAccess` outside Organizations and Service Provider Network, and `write` and `delete` on Integrations, Support & Contact and Email Templates — which is never granted, and which a save cannot grant. Where it is offered, `portalAccess` is never disabled by what else is ticked — the screen waits for `read`, `write`, `edit` and `delete` before letting it be ticked — but it is held only alongside all four, so a save ticking it without them saves nothing and clearing any of them clears it. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"RolePermissionGridRow":{"description":"One module's checkboxes, keyed by the `value`s in `levels` — or, for a group such as `settings`, no cells and a `modules` list of its sub-modules' rows instead. On save `moduleLabel` is ignored, a cell left out keeps its stored value, and a group row's `modules` are saved as if each were its own row.","required":["module"],"properties":{"module":{"type":"string","example":"finance"},"moduleLabel":{"type":"string","example":"Finances"},"modules":{"description":"Group rows only: the sub-modules' rows, each shaped like a module row. Settings has General, Assignments & Shifts, Broadcast & Dispatch Logic, Notifications & Preferences, Service Setup, Rates & Billing, Organization Locations, Restricted Users, Preferred Users, Integrations and Invoices.","type":"array","items":{"type":"object"}},"read":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"write":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"edit":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"delete":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"portalAccess":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"}},"type":"object"},"RolePermissionGrid":{"description":"The Settings → User & Access checkbox grid. GET /settings/role-permissions returns it as `data`; PUT /settings/role-permissions/{roleSlug} takes the same object back. On save `levels` is ignored.","required":["permissions"],"properties":{"levels":{"description":"The grid's columns, left to right.","type":"array","items":{"properties":{"value":{"type":"string","example":"read"},"label":{"type":"string","example":"Read"}},"type":"object"}},"permissions":{"type":"array","items":{"description":"One module's checkboxes, keyed by the `value`s in `levels` — or, for a group such as `settings`, no cells and a `modules` list of its sub-modules' rows instead. On save `moduleLabel` is ignored, a cell left out keeps its stored value, and a group row's `modules` are saved as if each were its own row.","required":["module"],"properties":{"module":{"type":"string","example":"finance"},"moduleLabel":{"type":"string","example":"Finances"},"modules":{"description":"Group rows only: the sub-modules' rows, each shaped like a module row. Settings has General, Assignments & Shifts, Broadcast & Dispatch Logic, Notifications & Preferences, Service Setup, Rates & Billing, Organization Locations, Restricted Users, Preferred Users, Integrations and Invoices.","type":"array","items":{"type":"object"}},"read":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"write":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"edit":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"delete":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"},"portalAccess":{"description":"One checkbox. `disabled` is true on an action the module does not offer — in a tenant, `portalAccess` outside Clients, Consumers and Providers, `write` on Handshakes, and `write`, `edit` and `delete` on Schedule and History & Logs; centrally, `portalAccess` outside Organizations, Service Provider Network and Consumer Network — which is never granted, and which a save cannot grant. `read` is never disabled, whatever else is ticked; clearing it removes the module. The `disabled` key itself is ignored on save.","required":["granted","disabled"],"properties":{"granted":{"type":"boolean","example":true},"disabled":{"type":"boolean","example":false}},"type":"object"}},"type":"object"}}},"type":"object"},"GuardianInput":{"description":"One guardian row on a consumer create/update. Matched to an existing guardian by id, then by email (case-insensitive); created only when neither matches.","required":["name","relationshipId"],"properties":{"id":{"type":"string","example":"GRD-ABC123","nullable":true},"name":{"type":"string","maxLength":255,"example":"Jane Doe"},"email":{"description":"Required (422 on guardians.N.email) when this guardian's portal access to the consumer is on, either by hasPortalAccess in this payload or as stored. Sent empty, it clears the stored address (needs a phone); left out, the stored address is kept","type":"string","format":"email","example":"jane@example.com","nullable":true},"countryCode":{"type":"string","example":"+1","nullable":true},"phone":{"description":"Email or phone is required","type":"string","example":"5551230000","nullable":true},"relationshipId":{"description":"Entry from GET /api/v1/guardian-relationships","type":"integer","example":1},"isPrimary":{"description":"Exactly one row is primary","type":"boolean","example":true},"receivesNotifications":{"type":"boolean","example":true},"hasPortalAccess":{"description":"This guardian's portal access to this consumer; omit to leave it as it is","type":"boolean","nullable":true}},"type":"object"}}},"security":[{"apiKey":[]}],"x-fido-generated-at":"2026-10-28T05:42:59+00:00","x-fido-source-sha256":"1026b39c8d875ffb15787a0ca9db6dbd0a66b4af09e0acf9c14fe8820b99a8b9","servers":[{"url":"https://api.fetchfido.ai","description":"Production"}],"x-tagGroups":[{"name":"Core","tags":["Connectivity","Assignments","Shifts","Clients","Consumers","Providers","Check Ins"]},{"name":"Scheduling and finance","tags":["Schedule","Requests","Finances","Team","Handshakes","Forms","History & Logs"]},{"name":"Settings","tags":["Settings · Assignments & Shifts","Settings · Broadcast & Dispatch Logic","Settings · General","Settings · Notifications & Preferences","Settings · Organization Locations","Settings · Preferred Users","Settings · Rates & Billing","Settings · Restricted Users","Settings · Service Setup"]}]}