{ "openapi": "3.1.0", "info": { "title": "Faximus Customer API", "version": "0.1.0", "summary": "Public customer API for programmable fax workflows.", "description": "Faximus is API-first fax infrastructure. This public contract documents only\ncustomer-safe, tenant-scoped API routes. Internal operator and admin routes\nare intentionally excluded.\n\nProduction is the supported deployment for customer integrations. API key\nenvironment labels do not establish a separate deployment or isolated test\nmode. Native test operations require the qualified schema-106 backend and an\nexplicitly selected test credential/session. Candidate source, SDKs and local\nfixtures do not establish backend activation; require exact release readback.", "contact": { "name": "Faximus Support", "email": "support@faximus.io" } }, "servers": [ { "url": "https://api.faximus.io", "description": "Production" } ], "tags": [ { "name": "Platform", "description": "Public health, readiness, discovery, and compatibility routes." }, { "name": "Authentication", "description": "Customer API key lifecycle for tenant-scoped integrations." }, { "name": "Account", "description": "Tenant profile, contact, cover page, DID, and usage readback." }, { "name": "Billing", "description": "Catalog, package selection, checkout, Customer Portal, billing usage, and entitlement readback." }, { "name": "Onboarding", "description": "Self-service signup, onboarding state, legal acceptance, BAA, PHI, consent, and opt-out preflight." }, { "name": "Documents", "description": "PDF upload, verification, preview, and short-lived document access." }, { "name": "Fax Jobs", "description": "Outbound fax submission, status, resend, and delivery readback." }, { "name": "Fax Batches", "description": "Independent multi-recipient sends, explicit bulk resends, failed-item retries, and private result exports." }, { "name": "Fax Presentation", "description": "Tenant-scoped outbound fax header/footer policy and asynchronous preview operations." }, { "name": "Phonebook", "description": "Shared tenant-scoped fax recipients plus private asynchronous CSV import and export." }, { "name": "Inbox", "description": "Customer-safe inbound fax readback and document access." }, { "name": "Email Fax", "description": "Customer-managed fax-to-email and email-to-fax configuration." }, { "name": "Webhooks", "description": "Customer-managed delivery event endpoints." } ], "externalDocs": { "description": "Faximus developer documentation", "url": "https://docs.faximus.io/" }, "paths": { "/openapi.yaml": { "get": { "tags": [ "Platform" ], "operationId": "getOpenApiYaml", "summary": "Download the public OpenAPI contract as YAML.", "security": [], "responses": { "200": { "description": "Public customer OpenAPI YAML.", "content": { "application/yaml": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Platform" ], "operationId": "getOpenApiJson", "summary": "Download the public OpenAPI contract as JSON.", "security": [], "responses": { "200": { "description": "Public customer OpenAPI JSON.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/health": { "get": { "tags": [ "Platform" ], "operationId": "getHealth", "summary": "Check whether the API process is alive.", "security": [], "responses": { "200": { "description": "The API process is healthy.", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "ok": { "value": "OK" } } } } } } } }, "/ready": { "get": { "tags": [ "Platform" ], "operationId": "getReady", "summary": "Check whether required runtime dependencies are ready.", "security": [], "responses": { "200": { "description": "Required dependencies are ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } }, "503": { "description": "One or more required dependencies are not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } } } } }, "/v1/health": { "get": { "tags": [ "Platform" ], "operationId": "getVersionedHealth", "summary": "Check whether the API process is alive from the versioned root.", "security": [], "responses": { "200": { "description": "The API process is healthy.", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "ok": { "value": "OK" } } } } } } } }, "/v1/ready": { "get": { "tags": [ "Platform" ], "operationId": "getVersionedReady", "summary": "Check whether dependencies are ready from the versioned root.", "security": [], "responses": { "200": { "description": "Required dependencies are ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } }, "503": { "description": "One or more required dependencies are not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } } } } }, "/v1": { "get": { "tags": [ "Platform" ], "operationId": "getApiRoot", "summary": "Discover public API links.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "API metadata and customer-safe links.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRootResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/signup": { "post": { "tags": [ "Onboarding" ], "operationId": "createCommercialSignup", "summary": "Start self-service customer signup.", "description": "Public customer signup route. Creates customer-owned onboarding state without operator privileges when accepted.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Idempotent replay of an existing signup.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Signup created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signup/setup-password": { "post": { "tags": [ "Onboarding" ], "operationId": "completeCommercialSignupSetupPassword", "summary": "Complete signup from a secure setup link.", "description": "Public one-time setup-token route. Verifies the signup link, sets the customer password, marks email verified, and invalidates the token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "password" ], "properties": { "token": { "type": "string", "minLength": 32 }, "password": { "type": "string", "minLength": 12 }, "environmentScope": { "type": "string", "enum": [ "nonprod", "prod" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Signup setup completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/onboarding": { "get": { "tags": [ "Onboarding" ], "operationId": "getCommercialOnboardingStatus", "summary": "Read current customer onboarding state.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current onboarding projection.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "milestones": { "$ref": "#/components/schemas/OnboardingMilestones" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/onboarding/milestones/refresh": { "post": { "tags": [ "Onboarding" ], "operationId": "refreshCommercialOnboardingMilestones", "summary": "Refresh durable account milestone observations from authoritative records.", "description": "Bodyless account-scoped refresh. Repeating unchanged source facts preserves the observation and its timestamps. Does not change eligibility, billing, providers, or send gates. Requires the native116 durable capability; historical observations begin when this capability is installed.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Persisted milestone observation and bounded history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "milestones": { "$ref": "#/components/schemas/OnboardingMilestones" } } } } } }, "400": { "description": "Any request body is rejected." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "description": "Durable milestone capability is unavailable." } } } }, "/v1/onboarding/readiness": { "get": { "tags": [ "Onboarding" ], "operationId": "getCustomerReadiness", "summary": "Read canonical action-specific eligibility and verified first use.", "description": "Account-scoped native118 current projection. Missing, conflicting or expired authority remains unknown or blocked. Eligibility is separate from verified first use; every effect checks authority again. Caller-supplied commercial assessments never grant access.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current authoritative readiness projection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReadinessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "description": "Canonical readiness capability is unavailable." } } } }, "/v1/onboarding/readiness/exceptions": { "post": { "tags": [ "Onboarding" ], "operationId": "annotateCustomerReadinessException", "summary": "Record an expiring scoped readiness annotation without granting access.", "description": "Interactive current owner or administrator only. The server binds the current action, required gate, dependency digest, eligibility version and actor. Exact replays retain their original annotation; conflicting identities or stale sources return 409. Annotations never waive capability, legal, spending or security checks and never establish successful first use.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReadinessExceptionCommand" } } } }, "responses": { "200": { "description": "Immutable annotation and current readiness, without access grants.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CustomerReadinessResponse" }, { "type": "object", "properties": { "exception": { "$ref": "#/components/schemas/CustomerReadinessException" }, "replayed": { "type": "boolean" } } } ] } } } }, "400": { "description": "Invalid annotation or a new expiry outside the next 24 hours. Caller authority claims are rejected." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "customer_readiness_exception_conflict; reload current scope/version before an explicit new request." }, "503": { "description": "Native readiness capability unavailable." } } } }, "/v1/onboarding/readiness/policy": { "post": { "tags": [ "Onboarding" ], "operationId": "updateCustomerReadinessPolicy", "summary": "Restrict the declared intended fax use with an explicit versioned selection.", "description": "Interactive current account owner or administrator only. No default or legacy backfill. Non-PHI only restricts use; regulated use remains unknown until independent canonical evidence is verified. Selection never grants PHI permission or proves document contents or compliance. Actor-bound request idempotency and optimistic versioning prevent stale changes.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReadinessPolicyCommand" } } } }, "responses": { "200": { "description": "Persisted restrictive policy and current canonical readiness; replayed indicates an exact owned request replay.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CustomerReadinessResponse" }, { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/CustomerReadinessPolicy" }, "replayed": { "type": "boolean" } } } ] } } } }, "400": { "description": "Invalid configuration; extra PHI, BAA, capability and entitlement claims are rejected." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "customer_readiness_policy_conflict; stale expectedVersion or a reused request identity. Read current policy before explicit retry." }, "503": { "description": "Native readiness capability unavailable." } } } }, "/v1/onboarding/readiness/recheck": { "post": { "tags": [ "Onboarding" ], "operationId": "recheckCustomerReadiness", "summary": "Recheck canonical readiness and retain changed state.", "description": "Bodyless interactive account owner or administrator command. Reads current canonical records and retains changed readiness with bounded history. Does not send faxes, buy numbers, retry accepted effects or grant access.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Rechecked canonical readiness.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReadinessResponse" } } } }, "400": { "description": "Any request body is rejected." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "description": "Canonical readiness capability is unavailable." } } } }, "/v1/onboarding/workflow": { "post": { "tags": [ "Onboarding" ], "operationId": "updateCommercialOnboardingWorkflow", "summary": "Set account onboarding channels and intended fax direction.", "description": "Interactive account owner or administrator configuration only. Server records determine capability and completion. Requires native117; uses optimistic versioning and request-scoped idempotency. Does not send faxes, purchase numbers, or change billing.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingWorkflowCommand" } } } }, "responses": { "200": { "description": "Persisted workflow configuration and current onboarding projection.", "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "tenantId", "accountId", "milestones", "workflow", "replayed" ], "properties": { "event": { "type": "string", "const": "commercial_onboarding_workflow_updated" }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "milestones": { "$ref": "#/components/schemas/OnboardingMilestones" }, "workflow": { "$ref": "#/components/schemas/OnboardingWorkflow" }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid configuration; status, proof and capability claims are not accepted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "onboarding_workflow_conflict; expectedVersion is stale or requestId was reused for different configuration. Read the current workflow before an explicit retry." }, "503": { "description": "Workflow configuration capability is unavailable." } } } }, "/v1/onboarding/transitions": { "post": { "tags": [ "Onboarding" ], "operationId": "transitionCommercialOnboarding", "summary": "Request a server-authorized onboarding transition.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Transition decision.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/onboarding/email-verification/refresh": { "post": { "tags": [ "Onboarding" ], "operationId": "refreshCommercialEmailVerification", "summary": "Refresh onboarding state from the customer email verification signal.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Email verification gate refresh result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/legal/documents": { "get": { "tags": [ "Onboarding" ], "operationId": "listCommercialLegalDocuments", "summary": "List legal documents required for onboarding.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Required legal document metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/legal/acceptances": { "post": { "tags": [ "Onboarding" ], "operationId": "acceptCommercialLegalDocuments", "summary": "Accept required legal documents as the customer account owner.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Legal acceptance receipt.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/baa": { "get": { "tags": [ "Onboarding" ], "operationId": "getCommercialBaaStatus", "summary": "Read customer BAA request status.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "BAA status and history.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Onboarding" ], "operationId": "requestCommercialBaa", "summary": "Request BAA review for the customer account.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "BAA request status.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/phi-eligibility": { "post": { "tags": [ "Onboarding" ], "operationId": "evaluateCommercialPhiEligibility", "summary": "Evaluate an advisory PHI assessment from caller input.", "description": "This assessment does not grant fax access and does not verify persisted legal or BAA acceptance. Use GET /v1/onboarding/readiness for canonical action-specific readiness.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "PHI eligibility decision.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/consent": { "post": { "tags": [ "Onboarding" ], "operationId": "saveCommercialConsentBasis", "summary": "Save customer consent basis metadata.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Consent basis record.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/opt-outs": { "post": { "tags": [ "Onboarding" ], "operationId": "saveCommercialOptOut", "summary": "Save a recipient opt-out record.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Opt-out recipient record.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/compliance-preflight": { "post": { "tags": [ "Onboarding" ], "operationId": "decideCommercialCompliancePreflight", "summary": "Evaluate consent, opt-out, and PHI preflight without sending fax work.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Compliance preflight decision.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/api-keys": { "get": { "tags": [ "Authentication" ], "operationId": "listApiKeys", "summary": "List tenant-scoped API keys.", "description": "Requires a signed-in customer portal session. API keys cannot manage API keys.", "x-faximus-required-scope": "customer-session", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "API key metadata. Plaintext key material is never returned by list operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Authentication" ], "operationId": "createApiKey", "summary": "Create a tenant-scoped API key.", "description": "Returns plaintext key material once. Store it immediately; later readback only shows metadata.", "x-faximus-required-scope": "customer-session", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" }, "examples": { "normalFaxIntegration": { "value": { "name": "Claims fax integration", "environment": "production", "scopeSet": [ "fax:send", "fax:read" ] } } } } } }, "responses": { "201": { "description": "API key created. Copy the plaintext key now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/api-keys/{apiKeyId}/revoke": { "post": { "tags": [ "Authentication" ], "operationId": "revokeApiKey", "summary": "Revoke an API key.", "description": "Requires a signed-in customer portal session.", "x-faximus-required-scope": "customer-session", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" } ], "responses": { "200": { "description": "API key metadata after revocation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/api-keys/{apiKeyId}": { "delete": { "tags": [ "Authentication" ], "operationId": "deleteApiKey", "summary": "Delete revoked API key metadata.", "description": "Requires a signed-in customer portal session. Active or disabled keys must be revoked before deletion.", "x-faximus-required-scope": "customer-session", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" } ], "responses": { "200": { "description": "API key metadata that was deleted. Plaintext key material is never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/account/activity": { "get": { "tags": [ "Account" ], "operationId": "listAccountActivity", "summary": "List customer-safe account activity across setup, billing, LOA, email fax, and fax delivery.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "account", "billing", "loa", "number_transfer", "email_fax", "fax_delivery", "inbox" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Use with category=email_fax to show email-to-fax activity, fax-to-email activity, or both.", "schema": { "type": "string", "enum": [ "email_to_fax", "fax_to_email", "all" ] } }, { "name": "reasonCode", "in": "query", "required": false, "description": "Use with category=email_fax or category=fax_delivery to filter by a customer-safe rejection or delivery status.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "requestId", "in": "query", "required": false, "description": "Limit activity to customer-safe records associated with a support request ID.", "schema": { "type": "string", "maxLength": 256 } }, { "name": "correlationId", "in": "query", "required": false, "description": "Limit activity to an outbound fax delivery record by customer-safe correlation ID. Do not combine with requestId.", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "Customer-safe account activity timeline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountActivityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/account/profile": { "get": { "tags": [ "Account" ], "operationId": "getAccountProfile", "summary": "Get the caller's tenant and customer account profile.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Tenant, account, membership, and contact profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountProfileResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "tags": [ "Account" ], "operationId": "updateAccountProfile", "summary": "Update customer account contact profile fields.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchCustomerAccountProfileRequest" }, "examples": { "contact": { "value": { "displayName": "Iron Health", "firstName": "Tony", "lastName": "Stark", "phoneNumber": "+15551234567", "address": { "line1": "10880 Malibu Point", "city": "Malibu", "region": "CA", "postalCode": "90265", "country": "US" } } } } } } }, "responses": { "200": { "description": "Updated tenant, account, membership, and contact profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountProfileResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/account/session-policy": { "patch": { "tags": [ "Account" ], "operationId": "updateAccountSessionPolicy", "summary": "Update the customer portal session TTL for the caller's account.", "description": "Requires an interactive customer owner or admin session. API keys, support impersonation, members, and internal operator credentials are rejected.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchCustomerAccountSessionPolicyRequest" }, "examples": { "fourHours": { "value": { "ttlSeconds": 14400 } } } } } }, "responses": { "200": { "description": "Updated account session policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountSessionPolicyUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/account/users": { "get": { "tags": [ "Account" ], "operationId": "listAccountUsers", "summary": "List workspace team members and pending invitations.", "description": "Owners, admins, and members can view the team. Manage permissions are returned so customer portals can render the right controls.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Workspace team members, pending invitations, and caller permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountUsersResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/account/user-invitations": { "post": { "tags": [ "Account" ], "operationId": "createAccountUserInvitation", "summary": "Invite a person to the workspace team.", "description": "Owners may invite owners, admins, and members. Admins may invite admins and members.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerUserInvitationRequest" }, "examples": { "invite": { "value": { "email": "teammate@example.com", "displayName": "Avery Stone", "role": "admin" } } } } } }, "responses": { "200": { "description": "Created invitation and safe delivery status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUserInvitationCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/account/user-invitations/{invitationId}": { "delete": { "tags": [ "Account" ], "operationId": "revokeAccountUserInvitation", "summary": "Revoke a pending workspace invitation.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InvitationId" } ], "responses": { "200": { "description": "Revoked invitation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUserInvitationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/user-invitations/{invitationId}/resend": { "post": { "tags": [ "Account" ], "operationId": "resendAccountUserInvitation", "summary": "Resend a pending workspace invitation.", "description": "Rotates the one-time invitation token, extends the 7-day expiry window, and sends the branded invitation email again. Reusing the same Idempotency-Key returns the saved safe delivery state. A different key receives a pending result while another resend holds the two-minute delivery lease. During rolling deployment the header is optional; clients should send it.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InvitationId" }, { "$ref": "#/components/parameters/InvitationResendIdempotencyKey" } ], "responses": { "200": { "description": "Resent invitation and safe delivery status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUserInvitationResentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/user-invitations/accept/{token}": { "get": { "tags": [ "Account" ], "operationId": "previewAccountUserInvitation", "summary": "Preview a workspace invitation before accepting it.", "description": "This public preview returns only safe invitation context needed to show the accept screen.", "security": [], "parameters": [ { "$ref": "#/components/parameters/InvitationToken" } ], "responses": { "200": { "description": "Safe invitation preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUserInvitationPreviewResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Account" ], "operationId": "acceptAccountUserInvitation", "summary": "Accept a workspace invitation.", "description": "The signed-in customer user must match the invited email address.", "x-faximus-required-scope": "customer-session", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InvitationToken" } ], "responses": { "200": { "description": "Accepted invitation and linked workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUserInvitationAcceptedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/account/users/{subject}": { "patch": { "tags": [ "Account" ], "operationId": "updateAccountUser", "summary": "Update a workspace team member.", "description": "Owners and admins can update team access within their role permissions. Self-removal and last-owner removal are blocked.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UserSubject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchCustomerAccountUserRequest" }, "examples": { "role": { "value": { "role": "member" } }, "active": { "value": { "isActive": false } } } } } }, "responses": { "200": { "description": "Updated team member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountUserResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "tags": [ "Account" ], "operationId": "deactivateAccountUser", "summary": "Deactivate a workspace team member.", "description": "Removes active workspace access without deleting historical records.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UserSubject" } ], "responses": { "200": { "description": "Deactivated team member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountUserResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/account/cover-page": { "get": { "tags": [ "Account", "Documents" ], "operationId": "getCoverPage", "summary": "Get the active default cover page.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active cover page or null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverPageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Account", "Documents" ], "operationId": "saveCoverPage", "summary": "Set the active default cover page.", "description": "The referenced document must be an uploaded, unattached, page-accounted PDF owned by the caller's account.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documentId" ], "properties": { "documentId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Saved cover page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverPageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "tags": [ "Account", "Documents" ], "operationId": "removeCoverPage", "summary": "Remove the active default cover page.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Cover page removal result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "removed", "coverPage" ], "properties": { "event": { "type": "string", "example": "customer_cover_page_removed" }, "removed": { "type": "boolean" }, "coverPage": { "type": [ "null", "object" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/usage/summary": { "get": { "tags": [ "Account" ], "operationId": "getUsageSummary", "summary": "Summarize tenant usage events.", "x-faximus-required-scope": "usage:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Tenant usage summary for the requested window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUsageSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/catalog": { "get": { "tags": [ "Billing" ], "operationId": "getBillingCatalog", "summary": "List active public packages and prices.", "security": [], "responses": { "200": { "description": "Active public catalog packages.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/billing": { "get": { "tags": [ "Billing" ], "operationId": "getBillingOverview", "summary": "Get customer billing overview.", "x-faximus-required-scope": "usage:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Billing account and subscription state.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "subscriptionChange": { "$ref": "#/components/schemas/SubscriptionPlanChangeOverview" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/billing/history": { "get": { "tags": [ "Billing" ], "operationId": "getBillingHistory", "summary": "List customer billing usage periods, invoices, and payment transactions.", "description": "Returns account-scoped internal usage history and a customer-safe live projection of Stripe invoices and charges. Stripe provider failures do not remove available internal usage history.", "x-faximus-required-scope": "usage:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }, { "name": "usageCursor", "in": "query", "schema": { "type": "string", "maxLength": 512 } }, { "name": "invoiceCursor", "in": "query", "schema": { "type": "string", "maxLength": 512 } }, { "name": "transactionCursor", "in": "query", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Customer-safe billing history. Responses are not cacheable.", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercialBillingHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/billing/cart": { "post": { "tags": [ "Billing" ], "operationId": "reviewBillingCart", "summary": "Review a package selection cart.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Reviewed cart.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/billing/promotion-code/validate": { "post": { "tags": [ "Billing" ], "operationId": "validateBillingPromotionCode", "summary": "Validate a Stripe promotion code for billing plan selection.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Promotion code validation result with sanitized coupon metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/billing/payment-setup": { "post": { "tags": [ "Billing" ], "operationId": "startBillingPaymentSetup", "summary": "Start hosted Stripe card-on-file setup for a reviewed paid cart.", "description": "Plan acceptance uses the exact server-reviewed cart fingerprint and notice version. When planAcceptance is supplied, Idempotency-Key and the selected commercial write runtime are required. Native122 requires a matching durable acceptance before activation or provider dispatch.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "planAcceptance": { "$ref": "#/components/schemas/CommercialPlanAcceptance" } } } } } }, "responses": { "200": { "description": "Hosted payment setup launch URL or cardless bypass result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/billing/checkout": { "post": { "tags": [ "Billing" ], "operationId": "startBillingCheckout", "summary": "Start Stripe Checkout for a reviewed cart.", "description": "Plan acceptance uses the exact server-reviewed cart fingerprint and notice version. When planAcceptance is supplied, Idempotency-Key and the selected commercial write runtime are required. Native122 requires a matching durable acceptance before provider dispatch.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "planAcceptance": { "$ref": "#/components/schemas/CommercialPlanAcceptance" } } } } } }, "responses": { "200": { "description": "Stripe Checkout launch URL and safe metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/billing/subscription/cancellation": { "post": { "tags": [ "Billing" ], "operationId": "confirmSubscriptionCancellation", "summary": "Stop automatic renewal at the reviewed period end.", "description": "Available to signed-in workspace owners and administrators when enabled. Check a pending receipt using the same effective date and an idempotency key. A pending receipt means Stripe has not confirmed the schedule. A recovery-required receipt permits status readback and needs billing support if Stripe still cannot confirm it.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "effectiveAt" ], "additionalProperties": false, "properties": { "effectiveAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Durable pending or confirmed cancellation receipt.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cancellation" ], "properties": { "cancellation": { "type": "object", "required": [ "status", "effectiveAt", "confirmationId" ], "properties": { "status": { "type": "string", "enum": [ "pending", "scheduled", "recovery_required" ] }, "effectiveAt": { "type": "string", "format": "date-time" }, "confirmationId": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/billing/subscription/change/preview": { "post": { "tags": [ "Billing" ], "operationId": "previewSubscriptionChange", "summary": "Review a change to an existing subscription.", "description": "Available to signed-in workspace owners when enabled. Returns a short-lived quote for the selected plan.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "targetPackageCode" ], "properties": { "targetPackageCode": { "type": "string", "enum": [ "payg", "starter", "growth", "business" ] } } } } } }, "responses": { "200": { "description": "Plan change quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanChangeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/billing/subscription/change": { "post": { "tags": [ "Billing" ], "operationId": "confirmSubscriptionChange", "summary": "Accept a reviewed subscription change or check its status.", "description": "Available to signed-in workspace owners when enabled. Send only changeId to check the current receipt. To accept a quote, send all three fields with Idempotency-Key. The current plan remains in effect while payment or renewal is pending.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for accepting a reviewed quote. Omit for a status check.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "changeId" ], "properties": { "changeId": { "type": "string", "format": "uuid" } } }, { "type": "object", "additionalProperties": false, "required": [ "changeId", "reviewFingerprint", "noticeVersion" ], "properties": { "changeId": { "type": "string", "format": "uuid" }, "reviewFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "noticeVersion": { "type": "string", "maxLength": 100 } } } ] } } } }, "responses": { "200": { "description": "Durable subscription change receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanChangeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/billing/portal": { "post": { "tags": [ "Billing" ], "operationId": "startBillingPortal", "summary": "Start a Stripe Customer Portal session.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Stripe Customer Portal launch URL and safe metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/billing/usage": { "get": { "tags": [ "Billing" ], "operationId": "getBillingUsage", "summary": "Get billable usage and reporting status.", "x-faximus-required-scope": "usage:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Billable usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUsageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/billing/webhooks/stripe": { "post": { "tags": [ "Billing" ], "operationId": "receiveStripeBillingWebhook", "summary": "Receive a Stripe billing webhook.", "security": [], "responses": { "200": { "description": "Webhook receipt state.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/entitlements/evaluate": { "post": { "tags": [ "Billing" ], "operationId": "evaluateEntitlements", "summary": "Evaluate a customer package entitlement decision.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Entitlement decision.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/numbers/search": { "post": { "tags": [ "Account" ], "operationId": "searchAvailableNumbers", "summary": "Search for available fax-capable numbers.", "description": "Returns dry-run or readback candidates only. A search response never claims provider ownership.", "x-faximus-required-scope": "did:manage", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberSearchRequest" } } } }, "responses": { "200": { "description": "Customer-safe number candidates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/numbers/reservations": { "post": { "tags": [ "Account" ], "operationId": "activateCustomerNumber", "summary": "Activate a selected fax number.", "description": "Activates an exact searched candidate when the account has active paid billing and available included or confirmed add-on allowance.", "x-faximus-required-scope": "did:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberReservationRequest" } } } }, "responses": { "201": { "description": "Fax number activation accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberReservationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/numbers/status": { "get": { "tags": [ "Account" ], "operationId": "getNumberStatus", "summary": "Get customer-safe number activation status.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Local assignment, reservation, and manual-review status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/port-requests": { "get": { "tags": [ "Account" ], "operationId": "listPortRequests", "summary": "List customer port-in requests.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Customer-safe port request statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortRequestListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Account" ], "operationId": "createPortRequest", "summary": "Create a local port-in request for review.", "description": "Captures local review data and document references. Provider submission requires a separate approved provider command.", "x-faximus-required-scope": "did:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortRequestCreateRequest" } } } }, "responses": { "201": { "description": "Local port request created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortRequestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/port-requests/loa-template": { "get": { "tags": [ "Account" ], "operationId": "getPortLoaTemplate", "summary": "Get a fillable Faximus LOA PDF template.", "description": "Returns a branded fillable PDF as base64 so customer portals can download it without exposing storage keys.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Fillable LOA template PDF payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortLoaTemplateResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/port-requests/loa-documents": { "post": { "tags": [ "Account" ], "operationId": "createPortLoaDocument", "summary": "Create a signed LOA document for a port request.", "description": "Generates a customer-owned signed PDF and stores it as an uploaded document that can be referenced by a port request.", "x-faximus-required-scope": "did:manage", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortLoaDocumentCreateRequest" } } } }, "responses": { "201": { "description": "Generated LOA document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortLoaDocumentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/dids": { "get": { "tags": [ "Account" ], "operationId": "listDids", "summary": "List active DIDs assigned to the caller's account.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Customer-owned DIDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDidsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/dids/{didId}": { "get": { "tags": [ "Account" ], "operationId": "getDid", "summary": "Get one active DID assigned to the caller's account.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DidId" } ], "responses": { "200": { "description": "Customer-owned DID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDidResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sender-identities": { "get": { "tags": [ "Account" ], "operationId": "listSenderIdentities", "summary": "List sender identities available to the caller's account.", "description": "Includes customer-assigned outbound DIDs and, for active Free Developer accounts, configured shared developer test senders. Shared senders are not customer-owned DIDs.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Available sender identities.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderIdentitiesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/dids/{didId}/decoration": { "get": { "tags": [ "Fax Presentation" ], "operationId": "getDidDecoration", "summary": "Get header and footer settings for an assigned outbound fax number.", "description": "Returns an explicit disabled version-zero configuration when no saved policy exists.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DidId" } ], "responses": { "200": { "description": "Current customer-safe assigned-number decoration configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationConfigurationResponse" }, "examples": { "disabled": { "$ref": "#/components/examples/DecorationDisabled" }, "enabled": { "$ref": "#/components/examples/DecorationEnabled" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } }, "put": { "tags": [ "Fax Presentation" ], "operationId": "updateDidDecoration", "summary": "Replace header and footer settings for an assigned outbound fax number.", "description": "Owners and admins can save an exact version-checked configuration. A stale If-Match value changes nothing and returns a reload-required conflict.", "x-faximus-required-scope": "did:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DidId" }, { "$ref": "#/components/parameters/DecorationIfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationPolicyUpdateRequest" }, "examples": { "enabled": { "value": { "header": { "enabled": true, "template": "From {{account_name}} | {{send_date}}", "alignment": "left" }, "footer": { "enabled": true, "template": "Page {{page_number}} of {{total_pages}}", "alignment": "right" } } } } } } }, "responses": { "200": { "description": "Saved configuration or the idempotent current configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationConfigurationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/shared-senders/{didId}/decoration": { "get": { "tags": [ "Fax Presentation" ], "operationId": "getSharedSenderDecoration", "summary": "Get the effective managed header and footer state for a shared sender.", "description": "Distinguishes enabled, disabled, and unavailable managed behavior. Customers cannot customize managed text, alignment, font, layout, or versions.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DidId" } ], "responses": { "200": { "description": "Effective managed shared-sender configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationConfigurationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } }, "put": { "tags": [ "Fax Presentation" ], "operationId": "updateSharedSenderDecoration", "summary": "Enable or disable the current managed decoration for this account.", "description": "Owners and admins can change only the account Boolean decision. Enabling requires a currently available Faximus-managed template.", "x-faximus-required-scope": "did:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DidId" }, { "$ref": "#/components/parameters/DecorationIfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedDecorationEnablementRequest" }, "examples": { "enabled": { "value": { "enabled": true } } } } } }, "responses": { "200": { "description": "Current effective managed shared-sender configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationConfigurationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/decoration-previews": { "post": { "tags": [ "Fax Presentation" ], "operationId": "createDecorationPreview", "summary": "Create an asynchronous representative header and footer preview.", "description": "Creates a private one-hour non-PHI preview operation. It does not create or send a fax, bill usage, or contact a carrier.", "x-faximus-required-scope": "did:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationPreviewCreateRequest" }, "examples": { "assignedDraft": { "value": { "sourceKind": "assigned_did", "didId": "77777777-7777-4777-8777-777777777777", "draft": { "header": { "enabled": true, "template": "{{sender_did}} | {{send_date}}", "alignment": "left" }, "footer": { "enabled": true, "template": "Page {{page_number}} of {{total_pages}}", "alignment": "right" } } } }, "managedShared": { "value": { "sourceKind": "shared_sender", "didId": "77777777-7777-4777-8777-777777777777" } } } } } }, "responses": { "202": { "description": "Preview operation accepted or idempotently replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationPreviewOperationResponse" }, "examples": { "accepted": { "$ref": "#/components/examples/DecorationPreviewAccepted" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/decoration-previews/{operationId}": { "get": { "tags": [ "Fax Presentation" ], "operationId": "getDecorationPreview", "summary": "Get preview operation status and private artifact metadata.", "description": "Artifact metadata never includes storage coordinates. Authorized download access is issued separately by the protected artifact route.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Current preview operation and optional artifact metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationPreviewOperationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "The one-hour preview artifact is no longer available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/decoration-previews/{operationId}/artifact": { "post": { "tags": [ "Fax Presentation" ], "operationId": "accessDecorationPreviewArtifact", "summary": "Create short-lived access to an available private preview PDF.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Short-lived access response for the authorized preview artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecorationPreviewArtifactAccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "The one-hour preview artifact is no longer available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/documents": { "post": { "tags": [ "Documents" ], "operationId": "createDocument", "summary": "Create a PDF upload slot.", "description": "Upload one PDF with the returned presigned POST fields, then call the complete endpoint before referencing the document in a fax job. Native test execution requires a stored test credential, X-Faximus-Mode: test, and protected activated schema106 readiness. Test documents use generated fixtures; test fax bodies contain only documentId/scenario. Every test mutation requires a retained Idempotency-Key and exact body. Reconcile uncertain acceptance without a new intent.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeDocumentOperationRequest" }, "examples": { "pdf": { "value": { "fileName": "claim-form.pdf", "contentType": "application/pdf", "sizeBytes": 1048576, "sha256": "8f14e45fceea167a5a36dedd4bea2543b14e45fceea167a5a36dedd4bea2543" } } } } } }, "responses": { "201": { "description": "Pending document upload slot and presigned POST fields.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateDocumentResponse" }, { "$ref": "#/components/schemas/NativeTestDocumentResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-faximus-native-test": { "schemaOrdinal": 106, "availability": "requires_protected_activated_readback", "businessMode": "test", "synthetic": true }, "parameters": [ { "$ref": "#/components/parameters/NativeBusinessMode" }, { "$ref": "#/components/parameters/NativeTestIdempotencyKey" } ] } }, "/v1/documents/{documentId}": { "get": { "tags": [ "Documents" ], "operationId": "getDocument", "summary": "Get a document upload record.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/NativeBusinessMode" } ], "responses": { "200": { "description": "Document upload status.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DocumentResponse" }, { "$ref": "#/components/schemas/NativeTestDocumentResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": " Native test execution requires a stored test credential, X-Faximus-Mode: test, and protected activated schema106 readiness. Test documents use generated fixtures; test fax bodies contain only documentId/scenario. Every test mutation requires a retained Idempotency-Key and exact body. Reconcile uncertain acceptance without a new intent.", "x-faximus-native-test": { "schemaOrdinal": 106, "availability": "requires_protected_activated_readback", "businessMode": "test", "synthetic": true } } }, "/v1/documents/{documentId}/complete": { "post": { "tags": [ "Documents" ], "operationId": "completeDocument", "summary": "Verify an uploaded PDF and mark it uploaded.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/NativeBusinessMode" }, { "$ref": "#/components/parameters/NativeTestIdempotencyKey" } ], "responses": { "200": { "description": "Document upload verification result.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DocumentResponse" }, { "$ref": "#/components/schemas/NativeTestDocumentResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "description": " Native test execution requires a stored test credential, X-Faximus-Mode: test, and protected activated schema106 readiness. Test documents use generated fixtures; test fax bodies contain only documentId/scenario. Every test mutation requires a retained Idempotency-Key and exact body. Reconcile uncertain acceptance without a new intent.", "x-faximus-native-test": { "schemaOrdinal": 106, "availability": "requires_protected_activated_readback", "businessMode": "test", "synthetic": true } } }, "/v1/fax-jobs": { "get": { "tags": [ "Fax Jobs" ], "operationId": "listFaxJobs", "summary": "List outbound fax jobs.", "description": "Returns only jobs owned by the caller's resolved customer account. Optional usageSummary is an account-wide activity observation, not billing or entitlement. Its fixed 90 UTC calendar days include today, with future records excluded at the database-derived asOf. Rolling 24 hours use the existing outbound quota status exclusions. Unknown accounting returns null page totals. Summary requests permit only limit and cursor alongside includeUsageSummary; list filters and duplicate summary parameters are rejected.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "includeUsageSummary", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include the fixed account-wide outbound page activity summary, independent of list pagination. Must appear at most once with the exact value true or false." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search text for customer-safe job fields such as correlation ID." }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/FaxJobStatus" } }, { "name": "deliveryState", "in": "query", "schema": { "$ref": "#/components/schemas/DeliveryState" } }, { "name": "createdFrom", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdTo", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Customer-owned fax jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxJobListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "tags": [ "Fax Jobs" ], "operationId": "createFaxJob", "summary": "Submit an outbound fax job.", "description": "Requires an Idempotency-Key. Each referenced document must belong to the\ncaller and be in uploaded status. A matching idempotent replay returns\nthe existing job; reusing the key with a different canonical payload\nreturns idempotency_conflict.\n\nPaid accounts may set highResolutionColorCopy to true. Faximus still\nsends the normal fax and adds a recipient instruction cover page with a\nsecure URL, passcode, and expiry for the private high-resolution copy. Native test execution requires a stored test credential, X-Faximus-Mode: test, and protected activated schema106 readiness. Test documents use generated fixtures; test fax bodies contain only documentId/scenario. Every test mutation requires a retained Idempotency-Key and exact body. Reconcile uncertain acceptance without a new intent.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/NativeBusinessMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeFaxJobOperationRequest" }, "examples": { "sendFax": { "value": { "senderIdentity": "+18643106131", "destinationNumber": "+15551234567", "documents": [ { "documentId": "7f067f97-26f6-4bc9-8a19-3c0df6f17db8" } ], "highResolutionColorCopy": true, "correlationId": "claim-10001", "metadata": { "department": "claims" } } } } } } }, "responses": { "200": { "description": "Existing fax job returned for a matching idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxJobResponse" } } } }, "201": { "description": "Fax job accepted and queued.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FaxJobResponse" }, { "$ref": "#/components/schemas/NativeTestFaxJobResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-faximus-native-test": { "schemaOrdinal": 106, "availability": "requires_protected_activated_readback", "businessMode": "test", "synthetic": true } } }, "/v1/fax-jobs/{jobId}": { "get": { "tags": [ "Fax Jobs" ], "operationId": "getFaxJob", "summary": "Get one outbound fax job.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/NativeBusinessMode" } ], "responses": { "200": { "description": "Customer-safe fax job readback.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FaxJobResponse" }, { "$ref": "#/components/schemas/NativeTestFaxJobResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": " Native test execution requires a stored test credential, X-Faximus-Mode: test, and protected activated schema106 readiness. Test documents use generated fixtures; test fax bodies contain only documentId/scenario. Every test mutation requires a retained Idempotency-Key and exact body. Reconcile uncertain acceptance without a new intent.", "x-faximus-native-test": { "schemaOrdinal": 106, "availability": "requires_protected_activated_readback", "businessMode": "test", "synthetic": true } } }, "/v1/fax-jobs/{jobId}/resend": { "post": { "tags": [ "Fax Jobs" ], "operationId": "resendFaxJob", "summary": "Resend a fax job with edited metadata.", "description": "Creates a new job from the prior job context and the supplied request body. Requires an Idempotency-Key.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFaxJobRequest" } } } }, "responses": { "200": { "description": "Existing resend job returned for a matching idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxJobResponse" } } } }, "201": { "description": "Resend job accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batches": { "get": { "tags": [ "Fax Batches" ], "operationId": "listFaxBatches", "summary": "List outbound fax batches.", "description": "Returns a stable newest-first page for the caller's resolved account. Use the opaque nextCursor unchanged.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FaxBatchPageSize" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Account-scoped fax batch page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatchPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batches/multi-send": { "post": { "tags": [ "Fax Batches" ], "operationId": "createMultiSendFaxBatch", "summary": "Send one document set to one through ten recipients.", "description": "Each recipient becomes an independent fax job. A recipient may be a\nmanually entered fax number or an active entry from the caller's shared\naccount phonebook. Reuse the same Idempotency-Key only when retrying the\nsame reviewed request.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMultiSendFaxBatchRequest" }, "examples": { "manualAndPhonebook": { "value": { "recipients": [ { "kind": "manual", "faxNumber": "+12025550123" }, { "kind": "phonebook", "entryId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" } ], "senderIdentity": "+18643106131", "documents": [ { "documentId": "7f067f97-26f6-4bc9-8a19-3c0df6f17db8" } ], "includeDefaultCoverPage": false, "highResolutionColorCopy": false, "correlationId": "claim-10001", "customerReference": "Radiology referrals" } } } } } }, "responses": { "200": { "description": "Exact existing batch returned for an idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatch" } } } }, "201": { "description": "New independent fax batch completed its atomic creation pass.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batches/bulk-resend": { "post": { "tags": [ "Fax Batches" ], "operationId": "createBulkResendFaxBatch", "summary": "Resend one through ten explicitly selected faxes.", "description": "Every selected source must belong to the caller's resolved account and\nmust have reached a terminal state. Faximus preserves safe source\nchoices but applies current sender, billing, compliance, formatting,\ncapacity, and access policy to every new fax. If any source was already\ndelivered, deliveredConfirmation must exactly match the documented\nphrase.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBulkResendFaxBatchRequest" } } } }, "responses": { "200": { "description": "Exact existing batch returned for an idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatch" } } } }, "201": { "description": "New independent resend batch completed its atomic creation pass.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batches/{batchId}": { "get": { "tags": [ "Fax Batches" ], "operationId": "getFaxBatch", "summary": "Read one outbound fax batch.", "description": "Returns immutable creation results plus a safe current lifecycle summary for linked fax jobs when available.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FaxBatchId" } ], "responses": { "200": { "description": "Account-scoped fax batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batches/{batchId}/failed-items/retry": { "post": { "tags": [ "Fax Batches" ], "operationId": "retryFailedFaxBatchItems", "summary": "Retry selected failed or skipped items as a new batch.", "description": "Only explicitly selected failed or skipped items from this batch are\neligible. Created and in-progress items are rejected. Current sender,\nbilling, compliance, formatting, capacity, and access policy is applied\nagain; original item results never change.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FaxBatchId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryFaxBatchItemsRequest" } } } }, "responses": { "200": { "description": "Exact existing retry batch returned for an idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatch" } } } }, "201": { "description": "New retry batch completed its atomic creation pass.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batches/{batchId}/result-exports": { "post": { "tags": [ "Fax Batches" ], "operationId": "createFaxBatchResultExport", "summary": "Create a private CSV result export for a terminal batch.", "description": "Creates an exact-version private export operation. The CSV contains customer-safe immutable item results in stable ordinal order.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FaxBatchId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFaxBatchResultExportRequest" } } } }, "responses": { "200": { "description": "Exact existing export operation returned for an idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatchResultExportOperation" } } } }, "202": { "description": "Export operation accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatchResultExportOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batch-result-exports/{operationId}": { "get": { "tags": [ "Fax Batches" ], "operationId": "getFaxBatchResultExport", "summary": "Read one private batch-result export operation.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Account-scoped export operation and safe progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatchResultExportOperation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-batch-result-exports/{operationId}/artifact-access": { "post": { "tags": [ "Fax Batches" ], "operationId": "accessFaxBatchResultExportArtifact", "summary": "Issue short-lived access to the exact private result CSV.", "description": "Access is available only after the export completes. The short-lived URL must not be logged or persisted.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Short-lived exact-version private artifact access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxBatchResultArtifactAccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/fax-jobs/{jobId}/document-access": { "post": { "tags": [ "Fax Jobs", "Documents" ], "operationId": "createComposedFaxDocumentAccess", "summary": "Create access to the final composed fax artifact.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" } ], "requestBody": { "$ref": "#/components/requestBodies/DocumentAccessRequest" }, "responses": { "200": { "description": "Short-lived signed document URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/fax-jobs/{jobId}/documents/{documentId}/document-access": { "post": { "tags": [ "Fax Jobs", "Documents" ], "operationId": "createOutboundDocumentAccess", "summary": "Create access to one outbound fax source document.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/DocumentId" } ], "requestBody": { "$ref": "#/components/requestBodies/DocumentAccessRequest" }, "responses": { "200": { "description": "Short-lived signed document URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/fax-jobs/{jobId}/documents/{documentId}/document-preview": { "post": { "tags": [ "Fax Jobs", "Documents" ], "operationId": "createOutboundDocumentPreview", "summary": "Create preview metadata for one outbound fax source document.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/DocumentId" } ], "requestBody": { "$ref": "#/components/requestBodies/DocumentPreviewRequest" }, "responses": { "200": { "description": "Preview page metadata and short-lived signed image URLs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/inbox": { "get": { "tags": [ "Inbox" ], "operationId": "listInbox", "summary": "List inbound fax records.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "importState", "in": "query", "schema": { "type": "string", "enum": [ "received", "importing", "imported", "failed" ] } }, { "name": "receivedFrom", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "receivedTo", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Customer-owned inbound faxes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInboxResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/inbox/{inboundFaxId}": { "get": { "tags": [ "Inbox" ], "operationId": "getInboxItem", "summary": "Get one inbound fax record.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InboundFaxId" } ], "responses": { "200": { "description": "Customer-owned inbound fax readback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInboxItem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/inbox/{inboundFaxId}/document-access": { "post": { "tags": [ "Inbox", "Documents" ], "operationId": "createInboundDocumentAccess", "summary": "Create access to one inbound fax document.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InboundFaxId" } ], "requestBody": { "$ref": "#/components/requestBodies/DocumentAccessRequest" }, "responses": { "200": { "description": "Short-lived signed document URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/inbox/{inboundFaxId}/document-preview": { "post": { "tags": [ "Inbox", "Documents" ], "operationId": "createInboundDocumentPreview", "summary": "Create preview metadata for one inbound fax document.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InboundFaxId" } ], "requestBody": { "$ref": "#/components/requestBodies/DocumentPreviewRequest" }, "responses": { "200": { "description": "Preview page metadata and short-lived signed image URLs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/email-fax/settings": { "get": { "tags": [ "Email Fax" ], "operationId": "getEmailFaxSettings", "summary": "Read fax email settings.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Fax-to-email and email-to-fax settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "tags": [ "Email Fax" ], "operationId": "patchEmailFaxSettings", "summary": "Update fax email preferences.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchEmailFaxSettingsRequest" } } } }, "responses": { "200": { "description": "Updated fax email preferences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxPreferencesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-fax/messages": { "get": { "tags": [ "Email Fax" ], "operationId": "listEmailFaxMessages", "summary": "List recent email-to-fax gateway activity.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "received", "validated", "queued", "delivered", "rejected", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Customer-safe email-to-fax gateway activity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxMessagesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/email-fax/messages/{messageId}/retries": { "post": { "tags": [ "Email Fax" ], "operationId": "retryEmailFaxMessage", "summary": "Retry an eligible failed email-to-fax message.", "x-faximus-required-scope": "fax:send", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable UUIDv4 retry intent. Reuse the exact value if the response outcome is uncertain.", "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Exact quoted retryAttemptCount captured when this retry intent is created. Reuse this header unchanged with the same Idempotency-Key after an uncertain response; use the latest readback only when creating a new intent.", "schema": { "type": "string", "pattern": "^\"[1-4]\"$" } } ], "responses": { "200": { "description": "Email-to-fax retry was queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRetryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/email-fax/domains": { "get": { "tags": [ "Email Fax" ], "operationId": "listEmailFaxDomains", "summary": "List verified source domains.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Source domains authorized for email-to-fax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxDomainsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "tags": [ "Email Fax" ], "operationId": "createEmailFaxDomain", "summary": "Request source domain verification.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailFaxDomainRequest" } } } }, "responses": { "200": { "description": "Source domain verification request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxDomainResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-fax/domains/{domainId}/verify": { "post": { "tags": [ "Email Fax" ], "operationId": "verifyEmailFaxDomain", "summary": "Verify a source domain TXT record.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DomainId" } ], "responses": { "200": { "description": "Verified source domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxDomainResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-fax/domains/{domainId}": { "delete": { "tags": [ "Email Fax" ], "operationId": "deleteEmailFaxDomain", "summary": "Disable a source domain.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DomainId" } ], "responses": { "200": { "description": "Disabled source domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxDomainResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/email-fax/recipients": { "get": { "tags": [ "Email Fax" ], "operationId": "listEmailFaxRecipients", "summary": "List fax-to-email recipients.", "x-faximus-required-scope": "fax:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Verified fax-to-email recipients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRecipientsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "tags": [ "Email Fax" ], "operationId": "createEmailFaxRecipient", "summary": "Request recipient email verification.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailFaxRecipientRequest" } } } }, "responses": { "200": { "description": "Recipient verification request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRecipientResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-fax/recipient-verification": { "get": { "tags": [ "Email Fax" ], "operationId": "getEmailFaxRecipientVerificationLanding", "summary": "Open the recipient email verification landing page.", "description": "Returns an inert HTML landing page. A recipient must explicitly submit the fragment-delivered verification credentials before verification is attempted.", "security": [], "responses": { "200": { "description": "Recipient email verification landing page.", "content": { "text/html": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Email Fax" ], "operationId": "confirmEmailFaxRecipientVerification", "summary": "Submit recipient email verification credentials.", "description": "Submits opaque verification credentials and always returns the same generic acknowledgement for every verification outcome.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRecipientVerificationConfirmationRequest" } } } }, "responses": { "200": { "description": "Generic recipient verification submission acknowledgement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRecipientVerificationSubmissionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/email-fax/recipients/{recipientId}/verify": { "get": { "tags": [ "Email Fax" ], "operationId": "verifyEmailFaxRecipientLink", "summary": "Open recovery guidance for a legacy recipient verification link.", "description": "This deprecated route is inert and never consumes verification credentials. Request a fresh verification email from the customer portal.", "deprecated": true, "security": [], "parameters": [ { "$ref": "#/components/parameters/RecipientId" } ], "responses": { "200": { "description": "Recipient verification recovery guidance.", "content": { "text/html": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Email Fax" ], "operationId": "verifyEmailFaxRecipient", "summary": "Verify a recipient email token.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RecipientId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "verificationToken" ], "additionalProperties": false, "properties": { "verificationToken": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } } } } }, "responses": { "200": { "description": "Verified recipient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRecipientResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/email-fax/recipients/{recipientId}/resend-verification": { "post": { "tags": [ "Email Fax" ], "operationId": "resendEmailFaxRecipientVerification", "summary": "Resend a recipient email verification link.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RecipientId" } ], "responses": { "200": { "description": "Verification email resent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRecipientResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/email-fax/recipients/{recipientId}": { "delete": { "tags": [ "Email Fax" ], "operationId": "deleteEmailFaxRecipient", "summary": "Disable a fax-to-email recipient.", "x-faximus-required-scope": "admin:tenant", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RecipientId" } ], "responses": { "200": { "description": "Disabled recipient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFaxRecipientResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/webhook-endpoints": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "List customer-managed webhook endpoints.", "x-faximus-required-scope": "webhook:manage", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Customer webhook endpoint metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWebhookEndpointListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Create a customer-managed webhook endpoint.", "description": "Returns the signing secret once. List and readback responses never include it.", "x-faximus-required-scope": "webhook:manage", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerWebhookEndpointRequest" }, "examples": { "deliveryWebhook": { "value": { "url": "https://hooks.example.test/fax", "safeLabel": "Primary delivery hook", "eventTypes": [ "fax.delivery.confirmed", "fax.delivery.failed", "fax.delivery.unconfirmed" ] } } } } } }, "responses": { "201": { "description": "Customer webhook endpoint created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWebhookEndpointResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/webhook-endpoints/{endpointId}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Get one customer-managed webhook endpoint.", "x-faximus-required-scope": "webhook:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "200": { "description": "Customer webhook endpoint metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWebhookEndpointResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhookEndpoint", "summary": "Update one customer-managed webhook endpoint.", "x-faximus-required-scope": "webhook:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchCustomerWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "Customer webhook endpoint updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWebhookEndpointResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Soft delete one customer-managed webhook endpoint.", "description": "Marks the endpoint deleted, stops future delivery attempts, and hides the endpoint from customer list and readback APIs while preserving audit history.", "x-faximus-required-scope": "webhook:manage", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "200": { "description": "Customer webhook endpoint deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWebhookEndpointResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/phonebook": { "get": { "tags": [ "Phonebook" ], "operationId": "listPhonebookEntries", "summary": "Search the shared account phonebook.", "description": "Members may list active entries. Owners and admins may explicitly include deleted entries. API keys require `phonebook:read` or `phonebook:write`.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 160 } }, { "name": "includeDeleted", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "active", "deleted", "all" ], "default": "active" } }, { "$ref": "#/components/parameters/PhonebookPageSize" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Stable normalized-name/public-ID keyset page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Phonebook" ], "operationId": "createPhonebookEntry", "summary": "Add a phonebook entry.", "description": "Owner/admin or `phonebook:write` scope required. Exact duplicates are not created; distinct same-number entries return a warning.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookEntryInput" } } } }, "responses": { "200": { "description": "Exact/deleted duplicate result or replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookMutationResult" } } } }, "201": { "description": "Entry created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookMutationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/phonebook/{entryId}": { "get": { "tags": [ "Phonebook" ], "operationId": "getPhonebookEntry", "summary": "Read one visible phonebook entry.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PhonebookEntryId" }, { "name": "includeDeleted", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Account-scoped phonebook entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookEntry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Phonebook" ], "operationId": "replacePhonebookEntry", "summary": "Replace an active phonebook entry.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PhonebookEntryId" }, { "$ref": "#/components/parameters/PhonebookIfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookEntryInput" } } } }, "responses": { "200": { "description": "Updated, unchanged, or duplicate result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookMutationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Phonebook" ], "operationId": "deletePhonebookEntry", "summary": "Soft-delete a phonebook entry.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PhonebookEntryId" }, { "$ref": "#/components/parameters/PhonebookIfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Deleted or idempotently unchanged result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookMutationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/phonebook/{entryId}/restore": { "post": { "tags": [ "Phonebook" ], "operationId": "restorePhonebookEntry", "summary": "Restore a soft-deleted phonebook entry after duplicate revalidation.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PhonebookEntryId" }, { "$ref": "#/components/parameters/PhonebookIfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Restored, unchanged, or duplicate result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookMutationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/phonebook/imports": { "post": { "tags": [ "Phonebook" ], "operationId": "createPhonebookImport", "summary": "Reserve a private CSV import upload.", "description": "Owner/admin or `phonebook:write` scope required. Import is create-only and capped at 10,000 rows and 5 MiB.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookImportCreateRequest" } } } }, "responses": { "202": { "description": "Private upload and operation reserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookImportUpload" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/phonebook/imports/{operationId}/preview": { "post": { "tags": [ "Phonebook" ], "operationId": "previewPhonebookImport", "summary": "Finalize the exact upload and generate an immutable preview.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookImportPreviewRequest" } } } }, "responses": { "202": { "description": "Preview generation accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/phonebook/imports/{operationId}/confirm": { "post": { "tags": [ "Phonebook" ], "operationId": "confirmPhonebookImport", "summary": "Confirm an exact unexpired preview for create-only execution.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookImportConfirmRequest" } } } }, "responses": { "202": { "description": "Confirmed import accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/phonebook/imports/{operationId}/cancel": { "post": { "tags": [ "Phonebook" ], "operationId": "cancelPhonebookImport", "summary": "Cancel an import before any row effect is committed.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperationCancelRequest" } } } }, "responses": { "200": { "description": "Import canceled or the exact cancellation replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/phonebook/imports/{operationId}": { "get": { "tags": [ "Phonebook" ], "operationId": "getPhonebookImport", "summary": "Read import preview/execution status and safe counts.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Account-scoped operation state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/phonebook/imports/{operationId}/results": { "get": { "tags": [ "Phonebook" ], "operationId": "listPhonebookImportResults", "summary": "List durable per-row import results.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/PhonebookPageSize" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Bounded row result page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookImportResultPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/phonebook/imports/{operationId}/artifact-access": { "post": { "tags": [ "Phonebook" ], "operationId": "accessPhonebookImportArtifact", "summary": "Issue short-lived access to the exact private import result.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Short-lived exact-version private access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookArtifactAccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/phonebook/exports": { "post": { "tags": [ "Phonebook" ], "operationId": "createPhonebookExport", "summary": "Generate a private streamed phonebook CSV export.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookExportRequest" } } } }, "responses": { "202": { "description": "Export accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/phonebook/exports/{operationId}": { "get": { "tags": [ "Phonebook" ], "operationId": "getPhonebookExport", "summary": "Read export status and safe counts.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Account-scoped export state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/phonebook/exports/{operationId}/cancel": { "post": { "tags": [ "Phonebook" ], "operationId": "cancelPhonebookExport", "summary": "Cancel an export before processing begins.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperationCancelRequest" } } } }, "responses": { "200": { "description": "Export canceled or the exact cancellation replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/phonebook/exports/{operationId}/artifact-access": { "post": { "tags": [ "Phonebook" ], "operationId": "accessPhonebookExportArtifact", "summary": "Issue short-lived access to the exact private export.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OperationId" } ], "responses": { "200": { "description": "Short-lived exact-version private access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhonebookArtifactAccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/imports": { "post": { "tags": [ "Phonebook" ], "operationId": "reserveContactTransferImport", "summary": "Reserve a private contact import and its upload.", "description": "Accepts Google Contacts CSV, Outlook CSV, generic CSV, Faximus CSV, and vCard 3 or 4. Upload completion starts analysis automatically.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferImportReservation" } } } }, "responses": { "201": { "description": "Transfer and exact private upload reserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferUpload" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/contact-transfers/imports/{transferId}/analyze": { "post": { "tags": [ "Phonebook" ], "operationId": "analyzeContactTransferImport", "summary": "Verify the exact private upload and start automatic analysis.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferUploadComplete" } } } }, "responses": { "202": { "description": "Analysis accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/imports/{transferId}/mapping": { "put": { "tags": [ "Phonebook" ], "operationId": "updateContactTransferMapping", "summary": "Save an explicit generic CSV mapping and rebuild review candidates.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" }, { "$ref": "#/components/parameters/ContactTransferIfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFieldMapping" } } } }, "responses": { "202": { "description": "Mapping revision accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/imports/{transferId}/review": { "patch": { "tags": [ "Phonebook" ], "operationId": "reviewContactTransferImport", "summary": "Apply a bounded selection or editable-field review revision.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferReviewCommand" } } } }, "responses": { "200": { "description": "Review revision committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/imports/{transferId}/confirm": { "post": { "tags": [ "Phonebook" ], "operationId": "confirmContactTransferImport", "summary": "Confirm the exact reviewed generation and create new contacts once.", "description": "Exact duplicates are skipped. Distinct contacts sharing a number may be created with a warning; existing contacts are never modified or restored.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferConfirmCommand" } } } }, "responses": { "200": { "description": "Import completed atomically or the exact result replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/imports/{transferId}/candidates": { "get": { "tags": [ "Phonebook" ], "operationId": "listContactTransferCandidates", "summary": "Page through the current import review candidates.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" }, { "$ref": "#/components/parameters/PhonebookPageSize" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Bounded candidate page with the latest review overlay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferCandidatePage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/contact-transfers/exports": { "post": { "tags": [ "Phonebook" ], "operationId": "startContactTransferExport", "summary": "Snapshot contacts and render a portable, Faximus backup, or vCard export.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferExportRequest" } } } }, "responses": { "202": { "description": "Immutable export snapshot accepted for rendering.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/{transferId}": { "get": { "tags": [ "Phonebook" ], "operationId": "getContactTransfer", "summary": "Read account-scoped transfer status, safe counts, and available actions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" } ], "responses": { "200": { "description": "Current durable transfer state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/contact-transfers/{transferId}/cancel": { "post": { "tags": [ "Phonebook" ], "operationId": "cancelContactTransfer", "summary": "Cancel an eligible import or export version.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferVersionCommand" } } } }, "responses": { "200": { "description": "Transfer canceled or exact result replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/{transferId}/retry": { "post": { "tags": [ "Phonebook" ], "operationId": "retryContactTransfer", "summary": "Retry an eligible failed transfer version without re-uploading.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferVersionCommand" } } } }, "responses": { "202": { "description": "Retry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/contact-transfers/{transferId}/artifact-access": { "post": { "tags": [ "Phonebook" ], "operationId": "accessContactTransferArtifact", "summary": "Issue short-lived access to the exact private result artifact.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ContactTransferId" } ], "responses": { "200": { "description": "Five-minute access to the exact object version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTransferArtifact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/fax-jobs/{jobId}/cancel": { "post": { "tags": [ "Fax jobs" ], "operationId": "cancelTestFaxJob", "summary": "Cancel one synthetic native test fax job.", "description": "Qualified native schema106 test mode only. Suppresses remaining simulator envelopes; never resends or cancels a live carrier fax. Requires stored test credential and exact empty JSON body. Missing admission denies before effects.", "x-faximus-required-scope": "fax:send", "x-faximus-native-test": { "schemaOrdinal": 106, "availability": "requires_protected_activated_readback", "businessMode": "test", "synthetic": true }, "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "name": "X-Faximus-Mode", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "test" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "responses": { "200": { "description": "Current synthetic job projection; already terminal jobs remain terminal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeTestFaxJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } } } }, "/v1/webhook-endpoints/{endpointId}/readiness": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookDeveloperReadiness", "summary": "Read currently authorized webhook controls.", "description": "Requires a current owner/admin customer session; API-key authentication is rejected. Availability depends on exact qualified backend admission and endpoint/mode/version state. Mutations are single-shot; after uncertain acceptance retain the identical operationId/body and reconcile before another action. HTTP callbacks are at least once: deduplicate the verified signed eventId. Test callbacks require explicit test mode, a retained authorized terminal synthetic job and same-mode safe endpoint; they never submit a fax or charge customer fax usage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" }, { "name": "X-Faximus-Mode", "in": "header", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "description": "Explicit business mode. Test requires qualified native schema106 and a matching current customer session; key environment labels do not choose mode." } ], "responses": { "200": { "description": "Read currently authorized webhook controls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookControlsReadiness" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Bounded account/global operation quota exhausted." }, "503": { "description": "Qualified developer admission or dependency unavailable; reconcile ambiguous mutation outcomes." } } } }, "/v1/webhook-endpoints/{endpointId}/signing-secret": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookSigningSecretState", "summary": "Read signing version metadata without revealing a secret.", "description": "Requires a current owner/admin customer session; API-key authentication is rejected. Availability depends on exact qualified backend admission and endpoint/mode/version state. Mutations are single-shot; after uncertain acceptance retain the identical operationId/body and reconcile before another action. HTTP callbacks are at least once: deduplicate the verified signed eventId. Test callbacks require explicit test mode, a retained authorized terminal synthetic job and same-mode safe endpoint; they never submit a fax or charge customer fax usage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" }, { "name": "X-Faximus-Mode", "in": "header", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "description": "Explicit business mode. Test requires qualified native schema106 and a matching current customer session; key environment labels do not choose mode." } ], "responses": { "200": { "description": "Read signing version metadata without revealing a secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningState" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Bounded account/global operation quota exhausted." }, "503": { "description": "Qualified developer admission or dependency unavailable; reconcile ambiguous mutation outcomes." } } } }, "/v1/webhook-endpoints/{endpointId}/signing-secret/rotate": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSigningSecret", "summary": "Rotate signing secret with bounded overlap.", "description": "Requires a current owner/admin customer session; API-key authentication is rejected. Availability depends on exact qualified backend admission and endpoint/mode/version state. Mutations are single-shot; after uncertain acceptance retain the identical operationId/body and reconcile before another action. HTTP callbacks are at least once: deduplicate the verified signed eventId. Test callbacks require explicit test mode, a retained authorized terminal synthetic job and same-mode safe endpoint; they never submit a fax or charge customer fax usage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" }, { "name": "X-Faximus-Mode", "in": "header", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "description": "Explicit business mode. Test requires qualified native schema106 and a matching current customer session; key environment labels do not choose mode." } ], "responses": { "200": { "description": "Rotate signing secret with bounded overlap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningOperationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An exact developer_version_conflict is a confirmed rejected signing operation. Refresh readiness before using a new operationId. Other failures can have uncertain acceptance: retain the original ID and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Bounded account/global operation quota exhausted." }, "503": { "description": "Qualified developer admission or dependency unavailable; reconcile ambiguous mutation outcomes." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRotationRequest" } } } } } }, "/v1/webhook-endpoints/{endpointId}/signing-secret/revoke": { "post": { "tags": [ "Webhooks" ], "operationId": "revokeWebhookSigningSecrets", "summary": "Emergency-revoke endpoint signing versions.", "description": "Requires a current owner/admin customer session; API-key authentication is rejected. Availability depends on exact qualified backend admission and endpoint/mode/version state. Mutations are single-shot; after uncertain acceptance retain the identical operationId/body and reconcile before another action. HTTP callbacks are at least once: deduplicate the verified signed eventId. Test callbacks require explicit test mode, a retained authorized terminal synthetic job and same-mode safe endpoint; they never submit a fax or charge customer fax usage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" }, { "name": "X-Faximus-Mode", "in": "header", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "description": "Explicit business mode. Test requires qualified native schema106 and a matching current customer session; key environment labels do not choose mode." } ], "responses": { "200": { "description": "Emergency-revoke endpoint signing versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningOperationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An exact developer_version_conflict is a confirmed rejected signing operation. Refresh readiness before using a new operationId. Other failures can have uncertain acceptance: retain the original ID and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Bounded account/global operation quota exhausted." }, "503": { "description": "Qualified developer admission or dependency unavailable; reconcile ambiguous mutation outcomes." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRevocationRequest" } } } } } }, "/v1/webhook-endpoints/{endpointId}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveryHistory", "summary": "Read bounded callback delivery and attempt history.", "description": "Requires a current owner/admin customer session; API-key authentication is rejected. Availability depends on exact qualified backend admission and endpoint/mode/version state. Mutations are single-shot; after uncertain acceptance retain the identical operationId/body and reconcile before another action. HTTP callbacks are at least once: deduplicate the verified signed eventId. Test callbacks require explicit test mode, a retained authorized terminal synthetic job and same-mode safe endpoint; they never submit a fax or charge customer fax usage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" }, { "name": "X-Faximus-Mode", "in": "header", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "description": "Explicit business mode. Test requires qualified native schema106 and a matching current customer session; key environment labels do not choose mode." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 }, "description": "Opaque five-minute same-scope cursor; may expire after process restart." } ], "responses": { "200": { "description": "Read bounded callback delivery and attempt history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookHistoryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Bounded account/global operation quota exhausted." }, "503": { "description": "Qualified developer admission or dependency unavailable; reconcile ambiguous mutation outcomes." } } } }, "/v1/webhook-endpoints/{endpointId}/deliveries/replay": { "post": { "tags": [ "Webhooks" ], "operationId": "replayWebhookDelivery", "summary": "Replay the same callback event without resending a fax.", "description": "Requires a current owner/admin customer session; API-key authentication is rejected. Availability depends on exact qualified backend admission and endpoint/mode/version state. Mutations are single-shot; after uncertain acceptance retain the identical operationId/body and reconcile before another action. HTTP callbacks are at least once: deduplicate the verified signed eventId. Test callbacks require explicit test mode, a retained authorized terminal synthetic job and same-mode safe endpoint; they never submit a fax or charge customer fax usage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" }, { "name": "X-Faximus-Mode", "in": "header", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "description": "Explicit business mode. Test requires qualified native schema106 and a matching current customer session; key environment labels do not choose mode." } ], "responses": { "200": { "description": "Replay the same callback event without resending a fax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReplayResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Bounded account/global operation quota exhausted." }, "503": { "description": "Qualified developer admission or dependency unavailable; reconcile ambiguous mutation outcomes." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReplayRequest" } } } } } }, "/v1/webhook-endpoints/{endpointId}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "sendTestWebhook", "summary": "Dispatch an explicit synthetic callback for a retained synthetic job.", "description": "Requires a current owner/admin customer session; API-key authentication is rejected. Availability depends on exact qualified backend admission and endpoint/mode/version state. Mutations are single-shot; after uncertain acceptance retain the identical operationId/body and reconcile before another action. HTTP callbacks are at least once: deduplicate the verified signed eventId. Test callbacks require explicit test mode, a retained authorized terminal synthetic job and same-mode safe endpoint; they never submit a fax or charge customer fax usage.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" }, { "name": "X-Faximus-Mode", "in": "header", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "description": "Explicit business mode. Test requires qualified native schema106 and a matching current customer session; key environment labels do not choose mode." } ], "responses": { "200": { "description": "Dispatch an explicit synthetic callback for a retained synthetic job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticWebhookTestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Bounded account/global operation quota exhausted." }, "503": { "description": "Qualified developer admission or dependency unavailable; reconcile ambiguous mutation outcomes." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticWebhookTestRequest" } } } } } }, "/v1/onboarding/readiness/recovery": { "get": { "tags": [ "Onboarding" ], "operationId": "getCustomerReadinessRecovery", "summary": "Read scoped readiness blockers and follow-up evidence.", "description": "Native119 coordination only. Canonical native118 eligibility and verified activation remain separate. Notes and ownership never grant permissions or repeat provider, fax, billing or notification effects. Exact command retries are actor-bound and versioned; after an uncertain response read current state before an explicit action. Support sessions are read-only.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current scoped evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessRecoveryResponse" } } } }, "400": { "description": "Invalid finite command or source reference." }, "401": { "description": "Authentication required." }, "403": { "description": "Scope or role denied." }, "409": { "description": "Source, ownership or version changed; read current state." }, "503": { "description": "Readback unavailable or command outcome unknown. Do not automatically retry." } } } }, "/v1/onboarding/readiness/recovery/commands": { "post": { "tags": [ "Onboarding" ], "operationId": "postCustomerReadinessRecoveryCommand", "summary": "Record a versioned readiness follow-up command.", "description": "Native119 coordination only. Canonical native118 eligibility and verified activation remain separate. Notes and ownership never grant permissions or repeat provider, fax, billing or notification effects. Exact command retries are actor-bound and versioned; after an uncertain response read current state before an explicit action. Support sessions are read-only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessRecoveryCommand" } } }, "description": "Exact current blocker and follow-up version; coordination only." }, "responses": { "200": { "description": "Recorded coordination receipt; current delivery acceptance is separate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessRecoveryResponse" } } } }, "400": { "description": "Invalid finite command or source reference." }, "401": { "description": "Authentication required." }, "403": { "description": "Scope or role denied." }, "409": { "description": "Source, ownership or version changed; read current state." }, "503": { "description": "Readback unavailable or command outcome unknown. Do not automatically retry." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Cognito JWT or Faximus API key", "description": "Use `Authorization: Bearer `.\n\nCustomer portal sessions are Cognito JWTs. Server-side integrations use\nFaximus API keys created from the customer portal. API key management\nendpoints require a customer portal session and reject API-key auth." } }, "parameters": { "ApiKeyId": { "name": "apiKeyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from the previous response." }, "FaxBatchId": { "name": "batchId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DurableOpaquePublicId" } }, "FaxBatchPageSize": { "name": "pageSize", "in": "query", "required": false, "description": "Number of newest-first fax batches to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "DidId": { "name": "didId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "DecorationIfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Exact quoted active version returned by the latest read, such as `\"0\"` or `\"3\"`.", "schema": { "type": "string", "pattern": "^\"[0-9]{1,10}\"$", "maxLength": 12 }, "example": "\"3\"" }, "DomainId": { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "DocumentId": { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "EndpointId": { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required for write operations that can safely be retried.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "claim-10001-send-001" }, "InvitationId": { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "InvitationResendIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "One key per deliberate resend action. Reuse the same key only for transport retry. Omission is temporarily supported for rolling compatibility.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "example": "team-resend-10001" }, "InvitationToken": { "name": "token", "in": "path", "required": true, "description": "One-time invitation token from the workspace invitation email.", "schema": { "type": "string", "minLength": 16, "maxLength": 256 } }, "OperationId": { "name": "operationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DurableOpaquePublicId" } }, "PhonebookEntryId": { "name": "entryId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DurableOpaquePublicId" } }, "PhonebookIfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Exact quoted phonebook entry version from the latest read.", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,18}\"$", "maxLength": 21 } }, "PhonebookPageSize": { "name": "pageSize", "in": "query", "required": false, "description": "Stable normalized-name/public-ID keyset page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "ContactTransferId": { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "ContactTransferIfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Exact quoted transfer version from the latest read.", "schema": { "type": "string", "pattern": "^\"[1-9][0-9]{0,15}\"$", "maxLength": 18 } }, "InboundFaxId": { "name": "inboundFaxId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "JobId": { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "RecipientId": { "name": "recipientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "UserSubject": { "name": "subject", "in": "path", "required": true, "description": "Cognito subject for the workspace user.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, "NativeBusinessMode": { "name": "X-Faximus-Mode", "in": "header", "required": false, "description": "Selection intent only; stored credential mode remains authoritative. Test mode needs qualified schema106 admission.", "schema": { "type": "string", "enum": [ "live", "test" ] } }, "NativeTestIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for each native test mutation; retain exact key/body. Existing live document behavior is unchanged.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "requestBodies": { "DocumentAccessRequest": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "disposition": { "type": "string", "enum": [ "inline", "download" ], "default": "download" } } }, "examples": { "download": { "value": { "disposition": "download" } } } } } }, "DocumentPreviewRequest": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "forceRender": { "type": "boolean", "default": false } } }, "examples": { "default": { "value": { "forceRender": false } } } } } } }, "responses": { "BadRequest": { "description": "Request is missing required headers or contains invalid JSON or fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Request conflicts with current state, idempotency, or account resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "DependencyUnavailable": { "description": "Required dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Caller is authenticated but lacks the required scope, entitlement, or tenant/account assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "Request could not be completed due to an internal dependency failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource was not found or is not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Public route request rate limit was exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Bearer token is missing, malformed, expired, or not valid for this API.", "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "examples": { "DecorationDisabled": { "summary": "Explicit assigned-number version-zero disabled configuration.", "value": { "version": 0, "sourceKind": "assigned_did", "state": "disabled", "managed": false, "globallyAvailable": null, "accountEnabled": null, "header": { "enabled": false, "template": null, "alignment": "left" }, "footer": { "enabled": false, "template": null, "alignment": "left" }, "templateGrammarVersion": "fax-decoration-template.v1", "layoutVersion": "fax-decoration-layout.v1", "fontId": "fax-decoration-font.noto-sans-regular.v1" } }, "DecorationEnabled": { "summary": "Enabled assigned-number header and footer configuration.", "value": { "version": 3, "sourceKind": "assigned_did", "state": "enabled", "managed": false, "globallyAvailable": null, "accountEnabled": null, "header": { "enabled": true, "template": "From {{account_name}} | {{send_date}}", "alignment": "left" }, "footer": { "enabled": true, "template": "Page {{page_number}} of {{total_pages}}", "alignment": "right" }, "templateGrammarVersion": "fax-decoration-template.v1", "layoutVersion": "fax-decoration-layout.v1", "fontId": "fax-decoration-font.noto-sans-regular.v1" } }, "DecorationPreviewAccepted": { "summary": "Accepted asynchronous private preview.", "value": { "operationId": "66666666-6666-4666-8666-666666666666", "type": "decoration_preview", "state": "accepted", "resultCode": null, "failureCode": null, "createdAt": "2026-07-30T12:00:00.000Z", "completedAt": null, "artifact": null } }, "DurableOperationAccepted": { "summary": "Accepted background account operation.", "value": { "operationId": "66666666-6666-4666-8666-666666666666", "operationType": "phonebook_import", "state": "accepted", "createdAt": "2026-07-29T22:00:00.000Z", "updatedAt": "2026-07-29T22:00:00.000Z" } }, "FaxBatchSummary": { "summary": "Partially completed fax batch summary.", "value": { "batchId": "77777777-7777-4777-8777-777777777777", "kind": "bulk_resend", "state": "completed_with_errors", "requestedCount": 3, "createdCount": 2, "skippedCount": 1, "failedCount": 0, "createdAt": "2026-07-29T22:00:00.000Z", "updatedAt": "2026-07-29T22:00:01.000Z" } } }, "schemas": { "SubscriptionPlanChangeTerms": { "type": "object", "required": [ "packageCode", "currencyCode", "billingInterval", "monthlyAmountCents", "includedPages", "includedFaxNumbers", "overageUnitAmountCents" ], "properties": { "packageCode": { "type": "string" }, "currencyCode": { "type": "string" }, "billingInterval": { "type": "string" }, "monthlyAmountCents": { "type": "integer", "minimum": 0 }, "includedPages": { "type": "integer", "minimum": 0 }, "includedFaxNumbers": { "type": "integer", "minimum": 0 }, "overageUnitAmountCents": { "type": "integer", "minimum": 0 } } }, "SubscriptionPlanChangeReceipt": { "type": "object", "required": [ "changeId", "status", "direction", "reviewFingerprint", "noticeVersion", "expiresAt", "currentPeriodEnd", "dueCents", "currencyCode", "currentPlan", "targetPlan" ], "properties": { "changeId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "quoted", "accepted", "awaiting_payment", "processing", "scheduled", "applied", "recovery_required", "abandoned" ] }, "direction": { "type": "string", "enum": [ "upgrade", "downgrade" ] }, "reviewFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "noticeVersion": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "paymentDeadline": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "dueCents": { "type": "integer", "minimum": 0 }, "subtotalCents": { "type": "integer", "minimum": 0 }, "currencyCode": { "type": "string", "const": "USD" }, "prorationDate": { "type": "integer", "minimum": 0 }, "paymentUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Stripe-hosted invoice link when the current upgrade awaits payment." }, "furtherChangesPending": { "type": "boolean", "description": "Another plan change is unavailable while the applied change's scheduled billing transition remains attached." }, "currentPlan": { "$ref": "#/components/schemas/SubscriptionPlanChangeTerms" }, "interimPlan": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionPlanChangeTerms" }, { "type": "null" } ] }, "targetPlan": { "$ref": "#/components/schemas/SubscriptionPlanChangeTerms" } } }, "SubscriptionPlanChangeOverview": { "type": "object", "required": [ "targets", "change" ], "properties": { "targets": { "type": "array", "items": { "type": "object", "required": [ "packageCode", "direction" ], "properties": { "packageCode": { "type": "string", "enum": [ "payg", "starter", "growth", "business" ] }, "direction": { "type": "string", "enum": [ "upgrade", "downgrade" ] } } } }, "change": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionPlanChangeReceipt" }, { "type": "null" } ] } } }, "SubscriptionPlanChangeResponse": { "type": "object", "required": [ "change" ], "properties": { "change": { "$ref": "#/components/schemas/SubscriptionPlanChangeReceipt" } } }, "CommercialPlanAcceptance": { "type": "object", "additionalProperties": false, "required": [ "accepted", "reviewedFingerprint", "noticeVersion" ], "properties": { "accepted": { "type": "boolean", "enum": [ true ] }, "reviewedFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "noticeVersion": { "type": "string", "enum": [ "faximus.plan-acceptance-notice.v1" ] } } }, "ReadinessRecoveryCommand": { "description": "Exact current blocker and follow-up version; coordination only.", "type": "object", "additionalProperties": false, "required": [ "requestId", "operation", "action", "gate", "dependencyDigest", "eligibilityVersion", "expectedVersion", "reasonCode", "expiresAt" ], "properties": { "requestId": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": [ "acknowledge", "assign-self", "release", "claim-handoff", "note", "recheck", "number-review-acknowledge", "number-review-assign-self", "number-review-release" ] }, "action": { "type": "string", "enum": [ "send", "receive", "numberAcquisition" ] }, "gate": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9-]{0,63}$" }, "dependencyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "eligibilityVersion": { "type": "integer", "minimum": 0, "maximum": 999999999 }, "expectedVersion": { "type": "integer", "minimum": 0, "maximum": 999999999 }, "reasonCode": { "type": "string", "enum": [ "investigating", "awaiting-customer", "awaiting-provider", "scheduled-review", "handoff", "recheck-requested" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "manualReview": { "type": "object", "additionalProperties": false, "required": [ "id", "expectedFingerprint" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expectedFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } }, "ReadinessRecoveryCommandReceipt": { "type": "object", "required": [ "receiptId", "requestId", "operation", "status", "version", "occurredAt", "beforeDigest", "afterDigest", "grantsAccess", "externalEffect" ], "properties": { "receiptId": { "type": "string", "format": "uuid" }, "requestId": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": [ "acknowledge", "assign-self", "release", "claim-handoff", "note", "recheck", "number-review-acknowledge", "number-review-assign-self", "number-review-release" ] }, "status": { "type": "string", "enum": [ "recorded" ] }, "version": { "type": "integer", "minimum": 0, "maximum": 999999999 }, "occurredAt": { "type": "string", "format": "date-time" }, "beforeDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "afterDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "grantsAccess": { "type": "boolean", "const": false }, "externalEffect": { "type": "boolean", "const": false } } }, "ReadinessRecovery": { "type": "object", "required": [ "contractVersion", "sourceVersion", "nativeOrdinal", "tenantId", "accountId", "environmentScope", "runtimeEnvironment", "readOnly", "visibility", "readiness", "blockers", "commandHistory", "notifications", "escalation", "grantsAccess", "externalEffect", "financialEffect" ], "properties": { "contractVersion": { "type": "string", "const": "readiness-recovery.v1" }, "sourceVersion": { "type": "string", "const": "native119" }, "nativeOrdinal": { "type": "integer", "const": 119 }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "environmentScope": { "type": "string", "enum": [ "prod", "nonprod" ] }, "runtimeEnvironment": { "type": "string", "enum": [ "production", "nonprod", "sandbox" ] }, "readOnly": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "customer", "operator", "support-safe" ] }, "readiness": { "$ref": "#/components/schemas/CustomerReadiness" }, "blockers": { "type": "array", "items": { "type": "object", "required": [ "key", "action", "gate", "status", "requiredTeam", "nextAction", "followup", "manualReviews" ], "properties": { "key": { "type": "string" }, "action": { "type": "string", "enum": [ "send", "receive", "numberAcquisition" ] }, "gate": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9-]{0,63}$" }, "status": { "type": "string" }, "requiredTeam": { "type": "string", "enum": [ "customer", "support", "billing", "number-operations", "security" ] }, "nextAction": { "type": "string", "enum": [ "recheck-readiness", "complete-customer-setup", "review-billing-state", "review-number-state", "review-security-policy", "review-source-evidence" ] }, "followup": { "type": "object", "required": [ "version", "status", "ownerKind", "ownerActorDigest", "reasonCode", "expiresAt", "sourceCurrent" ], "properties": { "version": { "type": "integer", "minimum": 0, "maximum": 999999999 }, "status": { "type": "string", "enum": [ "unacknowledged", "acknowledged", "owned", "handoff-pending", "expired", "source-changed" ] }, "ownerKind": { "type": [ "string", "null" ] }, "ownerActorDigest": { "type": [ "string", "null" ] }, "reasonCode": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "sourceCurrent": { "type": "boolean" } } }, "manualReviews": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "assigneeDigest", "fingerprint", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "assigneeDigest": { "type": [ "string", "null" ] }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } }, "commandHistory": { "type": "array", "items": { "type": "object", "required": [ "receiptId", "requestId", "operation", "status", "version", "occurredAt", "beforeDigest", "afterDigest", "grantsAccess", "externalEffect" ], "properties": { "receiptId": { "type": "string", "format": "uuid" }, "requestId": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": [ "acknowledge", "assign-self", "release", "claim-handoff", "note", "recheck", "number-review-acknowledge", "number-review-assign-self", "number-review-release" ] }, "status": { "type": "string", "enum": [ "recorded" ] }, "version": { "type": "integer", "minimum": 0, "maximum": 999999999 }, "occurredAt": { "type": "string", "format": "date-time" }, "beforeDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "afterDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "grantsAccess": { "type": "boolean", "const": false }, "externalEffect": { "type": "boolean", "const": false } } } }, "notifications": { "type": "object", "required": [ "status", "records" ], "properties": { "status": { "type": "string", "enum": [ "unknown", "available" ] }, "records": { "type": "array", "items": { "type": "object", "required": [ "status", "claimedAt", "sentAt", "deliveredAt", "source" ], "properties": { "status": { "type": "string", "enum": [ "claimed", "unknown" ] }, "claimedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "const": null, "description": "Always null: a pre-send claim does not establish send acceptance." }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time", "const": null, "description": "Always null: recipient delivery acknowledgement is unavailable." }, "source": { "type": "string", "const": "email-gateway-notification-claim.v1" } } } } } }, "escalation": { "type": "object", "required": [ "owner", "nextAction" ], "properties": { "owner": { "type": "string" }, "nextAction": { "type": "string" } } }, "grantsAccess": { "type": "boolean", "const": false }, "externalEffect": { "type": "boolean", "const": false }, "financialEffect": { "type": "boolean", "const": false } } }, "ReadinessRecoveryResponse": { "type": "object", "required": [ "event", "tenantId", "accountId", "recovery" ], "properties": { "event": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "recovery": { "$ref": "#/components/schemas/ReadinessRecovery" }, "commandReceipt": { "$ref": "#/components/schemas/ReadinessRecoveryCommandReceipt" }, "replayed": { "type": "boolean" } } }, "FaxBatchDocumentChoice": { "type": "object", "additionalProperties": false, "required": [ "documentId" ], "properties": { "documentId": { "$ref": "#/components/schemas/DurableOpaquePublicId" } } }, "FaxBatchManualRecipientChoice": { "type": "object", "additionalProperties": false, "required": [ "kind", "faxNumber" ], "properties": { "kind": { "type": "string", "const": "manual" }, "faxNumber": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } } }, "FaxBatchPhonebookRecipientChoice": { "type": "object", "additionalProperties": false, "required": [ "kind", "entryId" ], "properties": { "kind": { "type": "string", "const": "phonebook" }, "entryId": { "$ref": "#/components/schemas/DurableOpaquePublicId" } } }, "FaxBatchRecipientChoice": { "oneOf": [ { "$ref": "#/components/schemas/FaxBatchManualRecipientChoice" }, { "$ref": "#/components/schemas/FaxBatchPhonebookRecipientChoice" } ], "discriminator": { "propertyName": "kind", "mapping": { "manual": "#/components/schemas/FaxBatchManualRecipientChoice", "phonebook": "#/components/schemas/FaxBatchPhonebookRecipientChoice" } } }, "CreateMultiSendFaxBatchRequest": { "type": "object", "additionalProperties": false, "required": [ "recipients", "senderIdentity", "documents" ], "properties": { "recipients": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/FaxBatchRecipientChoice" } }, "senderIdentity": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$", "maxLength": 128 }, "documents": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/FaxBatchDocumentChoice" } }, "includeDefaultCoverPage": { "type": "boolean", "default": false }, "highResolutionColorCopy": { "type": "boolean", "default": false }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "customerReference": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "CreateBulkResendFaxBatchRequest": { "type": "object", "additionalProperties": false, "required": [ "sourceJobIds" ], "properties": { "sourceJobIds": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/components/schemas/DurableOpaquePublicId" } }, "deliveredConfirmation": { "type": "string", "enum": [ "RESEND DELIVERED FAXES" ], "description": "Required only when at least one selected source was already delivered." } } }, "RetryFaxBatchItemsRequest": { "type": "object", "additionalProperties": false, "required": [ "sourceItemIds" ], "properties": { "sourceItemIds": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/components/schemas/DurableOpaquePublicId" } }, "deliveredConfirmation": { "type": "string", "enum": [ "RESEND DELIVERED FAXES" ], "description": "Required only when a selected retry originated from a delivered fax." } } }, "CreateFaxBatchResultExportRequest": { "type": "object", "additionalProperties": false, "properties": { "csvVersion": { "type": "string", "const": "fax-batch-result-csv.v1", "default": "fax-batch-result-csv.v1" } } }, "FaxBatchCounts": { "type": "object", "additionalProperties": false, "required": [ "requested", "created", "skipped", "failed", "pending" ], "properties": { "requested": { "type": "integer", "minimum": 1, "maximum": 10 }, "created": { "type": "integer", "minimum": 0, "maximum": 10 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 10 }, "failed": { "type": "integer", "minimum": 0, "maximum": 10 }, "pending": { "type": "integer", "minimum": 0, "maximum": 10 } } }, "FaxBatchRecipient": { "type": "object", "additionalProperties": false, "required": [ "source", "phonebookEntryId", "displayName", "faxNumber" ], "properties": { "source": { "type": "string", "enum": [ "manual", "phonebook", "source_job", "retry_item" ] }, "phonebookEntryId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "displayName": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "faxNumber": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } } }, "FaxBatchItemResult": { "type": "object", "additionalProperties": false, "required": [ "state", "reasonCode", "message" ], "properties": { "state": { "type": "string", "enum": [ "reserved", "created", "skipped", "failed" ] }, "reasonCode": { "type": "string", "enum": [ "pending", "fax_created", "account_unavailable", "sender_unavailable", "document_unavailable", "plan_unavailable", "billing_unavailable", "consent_required", "recipient_unavailable", "try_again_later", "high_resolution_unavailable", "fax_formatting_unavailable", "source_fax_unavailable", "source_fax_not_finished", "fax_creation_failed", "fax_unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 240 } } }, "FaxBatchCurrentFax": { "type": "object", "additionalProperties": false, "required": [ "faxJobId", "state", "createdAt", "updatedAt", "completedAt" ], "properties": { "faxJobId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "state": { "type": "string", "enum": [ "received", "queued", "rendering", "rendered", "processing", "dispatching", "retrying", "completed", "failed", "canceled", "dead_lettered" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FaxBatchItemRetryCapability": { "type": "object", "additionalProperties": false, "required": [ "eligible", "requiresDeliveredConfirmation" ], "properties": { "eligible": { "type": "boolean" }, "requiresDeliveredConfirmation": { "type": "boolean", "description": "True when retrying this failed item requires the exact delivered-fax confirmation phrase." } } }, "FaxBatchItem": { "type": "object", "additionalProperties": false, "required": [ "faxBatchItemId", "ordinal", "recipient", "result", "faxJobId", "sourceFaxJobId", "sourceFaxBatchId", "sourceFaxBatchItemId", "estimatedPages", "retry", "currentFax", "createdAt", "completedAt" ], "properties": { "faxBatchItemId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 9 }, "recipient": { "$ref": "#/components/schemas/FaxBatchRecipient" }, "result": { "$ref": "#/components/schemas/FaxBatchItemResult" }, "faxJobId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "sourceFaxJobId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "sourceFaxBatchId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "sourceFaxBatchItemId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "estimatedPages": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Estimated pages, or zero when the document could not be inspected before the item failed closed." }, "retry": { "$ref": "#/components/schemas/FaxBatchItemRetryCapability" }, "currentFax": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FaxBatchCurrentFax" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FaxBatchCapabilities": { "type": "object", "additionalProperties": false, "required": [ "canRetryFailedItems", "canExportResults" ], "properties": { "canRetryFailedItems": { "type": "boolean" }, "canExportResults": { "type": "boolean" } } }, "FaxBatch": { "type": "object", "additionalProperties": false, "required": [ "faxBatchId", "kind", "state", "counts", "items", "sourceFaxBatchId", "capabilities", "createdAt", "updatedAt", "completedAt" ], "properties": { "faxBatchId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "kind": { "type": "string", "enum": [ "multi_send", "bulk_resend" ] }, "state": { "type": "string", "enum": [ "creating", "planning", "complete", "partial", "failed" ] }, "counts": { "$ref": "#/components/schemas/FaxBatchCounts" }, "items": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/FaxBatchItem" } }, "sourceFaxBatchId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "capabilities": { "$ref": "#/components/schemas/FaxBatchCapabilities" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FaxBatchListItem": { "type": "object", "additionalProperties": false, "required": [ "faxBatchId", "kind", "state", "requestedCount", "createdAt", "updatedAt", "completedAt" ], "properties": { "faxBatchId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "kind": { "type": "string", "enum": [ "multi_send", "bulk_resend" ] }, "state": { "type": "string", "enum": [ "creating", "planning", "complete", "partial", "failed" ] }, "requestedCount": { "type": "integer", "minimum": 1, "maximum": 10 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FaxBatchPage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor", "pageSize" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/FaxBatchListItem" } }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 2048 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "FaxBatchResultExportOperation": { "type": "object", "additionalProperties": false, "required": [ "operationId", "faxBatchId", "state", "csvVersion", "rowCount", "byteCount", "artifactId", "createdAt", "updatedAt", "completedAt", "expiresAt" ], "properties": { "operationId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "faxBatchId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "state": { "type": "string", "enum": [ "accepted", "queued", "processing", "completed", "failed", "canceled", "expired", "reconciliation_required" ] }, "csvVersion": { "type": "string", "const": "fax-batch-result-csv.v1" }, "rowCount": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 }, "byteCount": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1048576 }, "artifactId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "FaxBatchResultArtifactAccess": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "accessUrl", "expiresAt", "contentType", "csvVersion" ], "properties": { "artifactId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "accessUrl": { "type": "string", "format": "uri", "maxLength": 4096, "description": "Short-lived private exact-version URL; never log or persist it." }, "expiresAt": { "type": "string", "format": "date-time" }, "contentType": { "type": "string", "const": "text/csv" }, "csvVersion": { "type": "string", "const": "fax-batch-result-csv.v1" } } }, "PhonebookEntryInput": { "type": "object", "additionalProperties": false, "required": [ "displayName", "faxNumber" ], "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "faxNumber": { "type": "string", "minLength": 8, "maxLength": 64, "description": "Supported E.164 or human-friendly fax number. Stored canonically as E.164.", "example": "(202) 555-0123" }, "organization": { "type": [ "string", "null" ], "maxLength": 160 }, "contactName": { "type": [ "string", "null" ], "maxLength": 160 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "PhonebookEntry": { "type": "object", "additionalProperties": false, "required": [ "phonebookEntryId", "version", "state", "displayName", "faxNumber", "faxNumberDisplay", "organization", "contactName", "notes", "createdAt", "updatedAt", "deletedAt" ], "properties": { "phonebookEntryId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "version": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "active", "deleted" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "faxNumber": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" }, "faxNumberDisplay": { "type": "string", "minLength": 3, "maxLength": 32 }, "organization": { "type": [ "string", "null" ], "maxLength": 160 }, "contactName": { "type": [ "string", "null" ], "maxLength": 160 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PhonebookCapabilities": { "type": "object", "additionalProperties": false, "required": [ "canRead", "canMutate", "canExportDeleted" ], "properties": { "canRead": { "type": "boolean" }, "canMutate": { "type": "boolean" }, "canExportDeleted": { "type": "boolean" } } }, "PhonebookPage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor", "pageSize", "capabilities" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PhonebookEntry" } }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 2048 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "capabilities": { "$ref": "#/components/schemas/PhonebookCapabilities" } } }, "PhonebookMutationResult": { "type": "object", "additionalProperties": false, "required": [ "status", "entry", "warning", "currentVersion", "idempotentReplay" ], "properties": { "status": { "type": "string", "enum": [ "created", "updated", "deleted", "restored", "unchanged", "exact_duplicate", "deleted_exact_match" ] }, "entry": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PhonebookEntry" } ] }, "warning": { "type": "string", "enum": [ "none", "same_number_warning" ] }, "currentVersion": { "type": [ "integer", "null" ], "minimum": 1 }, "idempotentReplay": { "type": "boolean" } } }, "PhonebookImportCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "fileName", "contentType", "sizeBytes", "sha256", "csvVersion" ], "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "enum": [ "text/csv", "application/csv" ] }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 5242880 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "csvVersion": { "type": "string", "const": "phonebook-csv.v1" } } }, "PhonebookImportUpload": { "type": "object", "additionalProperties": false, "required": [ "operationId", "uploadId", "uploadUrl", "uploadFields", "expiresAt", "csvVersion" ], "properties": { "operationId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "uploadId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "uploadUrl": { "type": "string", "format": "uri", "maxLength": 4096, "description": "Short-lived private upload URL; never log or persist it." }, "uploadFields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Exact short-lived private upload fields; never log or persist them." }, "expiresAt": { "type": "string", "format": "date-time" }, "csvVersion": { "type": "string", "const": "phonebook-csv.v1" } } }, "PhonebookImportPreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "uploadId", "objectVersion", "sizeBytes", "sha256", "csvVersion" ], "properties": { "uploadId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "objectVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 5242880 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "csvVersion": { "type": "string", "const": "phonebook-csv.v1" } } }, "PhonebookImportConfirmRequest": { "type": "object", "additionalProperties": false, "required": [ "expectedOperationVersion", "previewFingerprint" ], "properties": { "expectedOperationVersion": { "type": "integer", "minimum": 1 }, "previewFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "PhonebookOperationCancelRequest": { "type": "object", "additionalProperties": false, "required": [ "expectedOperationVersion" ], "properties": { "expectedOperationVersion": { "type": "integer", "minimum": 1 } } }, "PhonebookOperationCounts": { "type": "object", "additionalProperties": false, "required": [ "total", "created", "exactDuplicate", "sameNumber", "invalid", "failed" ], "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 50000 }, "created": { "type": "integer", "minimum": 0, "maximum": 50000 }, "exactDuplicate": { "type": "integer", "minimum": 0, "maximum": 50000 }, "sameNumber": { "type": "integer", "minimum": 0, "maximum": 50000 }, "invalid": { "type": "integer", "minimum": 0, "maximum": 50000 }, "failed": { "type": "integer", "minimum": 0, "maximum": 50000 } } }, "PhonebookOperation": { "type": "object", "additionalProperties": false, "required": [ "operationId", "operationType", "state", "version", "counts", "createdAt", "updatedAt", "completedAt", "expiresAt", "previewFingerprint" ], "properties": { "operationId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "operationType": { "type": "string", "enum": [ "phonebook_import", "phonebook_export" ] }, "state": { "type": "string", "enum": [ "accepted", "previewing", "awaiting_confirmation", "queued", "processing", "completed", "completed_with_errors", "failed", "canceled", "expired", "reconciliation_required" ] }, "version": { "type": "integer", "minimum": 1 }, "counts": { "$ref": "#/components/schemas/PhonebookOperationCounts" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "previewFingerprint": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$", "description": "Exact immutable preview fingerprint required only when confirming a phonebook import." } } }, "PhonebookImportResult": { "type": "object", "additionalProperties": false, "required": [ "rowNumber", "outcome", "reasonCode", "warning", "phonebookEntryId" ], "properties": { "rowNumber": { "type": "integer", "minimum": 1, "maximum": 10000 }, "outcome": { "type": "string", "enum": [ "created", "skipped", "failed" ] }, "reasonCode": { "type": "string", "enum": [ "created", "exact_duplicate", "same_number_warning", "invalid_display_name", "invalid_fax_number", "invalid_organization", "invalid_contact_name", "invalid_notes", "persistence_failure" ] }, "warning": { "type": "string", "enum": [ "none", "same_number_warning" ] }, "phonebookEntryId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] } } }, "PhonebookImportResultPage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor", "pageSize" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PhonebookImportResult" } }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 2048 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "PhonebookExportRequest": { "type": "object", "additionalProperties": false, "required": [ "includeActive", "includeDeleted", "csvVersion" ], "properties": { "includeActive": { "type": "boolean" }, "includeDeleted": { "type": "boolean", "description": "Owner/admin or equivalent API-key write authority required when true." }, "csvVersion": { "type": "string", "const": "phonebook-csv.v1" } } }, "PhonebookArtifactAccess": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "accessUrl", "expiresAt", "contentType" ], "properties": { "artifactId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "accessUrl": { "type": "string", "format": "uri", "maxLength": 4096, "description": "Short-lived private exact-version URL; never log or persist it." }, "expiresAt": { "type": "string", "format": "date-time" }, "contentType": { "type": "string", "enum": [ "text/csv" ] } } }, "ContactTransferImportReservation": { "type": "object", "additionalProperties": false, "required": [ "fileName", "contentType", "sizeBytes", "sha256", "contractVersion" ], "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "enum": [ "text/csv", "application/csv", "text/vcard", "text/x-vcard" ] }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 5242880 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sourceFormat": { "type": "string", "enum": [ "auto", "faximus_csv_v1", "faximus_backup_csv_v1", "google_contacts_csv", "outlook_contacts_csv", "generic_csv", "vcard_3", "vcard_4" ], "default": "auto" }, "defaultRegion": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Optional default country/region for national phone numbers." }, "contractVersion": { "type": "string", "const": "contact-transfer.v2" } }, "example": { "fileName": "contacts.csv", "contentType": "text/csv", "sizeBytes": 4096, "sha256": "8d969eef6ecad3c29a3a629280e686cff8cae62c17ad3f65a2a4c0f3014e147", "sourceFormat": "auto", "defaultRegion": "US", "contractVersion": "contact-transfer.v2" } }, "ContactTransferUpload": { "type": "object", "additionalProperties": false, "required": [ "transfer", "uploadId", "uploadUrl", "uploadFields", "expiresAt" ], "properties": { "transfer": { "$ref": "#/components/schemas/ContactTransfer" }, "uploadId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string", "format": "uri", "maxLength": 4096, "description": "Short-lived private upload URL; never log or persist it." }, "uploadFields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Exact short-lived private upload fields; never log or persist them." }, "expiresAt": { "type": "string", "format": "date-time" } } }, "ContactTransferUploadComplete": { "type": "object", "additionalProperties": false, "required": [ "uploadId", "objectVersion", "sizeBytes", "sha256", "expectedVersion" ], "properties": { "uploadId": { "type": "string", "format": "uuid" }, "objectVersion": { "type": "string", "minLength": 1, "maxLength": 1024 }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 5242880 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expectedVersion": { "type": "integer", "minimum": 1 } } }, "ContactFieldReference": { "type": "object", "additionalProperties": false, "required": [ "position", "normalizedName" ], "properties": { "position": { "type": "integer", "minimum": 0, "maximum": 255 }, "normalizedName": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "ContactFieldMapping": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "sourceFormat", "sourceDigest", "sourceVersion", "adapterVersion", "mappingVersion", "numberSource" ], "properties": { "schemaVersion": { "type": "string", "const": "contact-field-mapping.v1" }, "sourceFormat": { "type": "string", "enum": [ "faximus_csv_v1", "faximus_backup_csv_v1", "google_contacts_csv", "outlook_contacts_csv", "generic_csv", "vcard_3", "vcard_4" ] }, "sourceDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sourceVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "adapterVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "mappingVersion": { "type": "integer", "minimum": 1, "maximum": 10000 }, "numberSource": { "$ref": "#/components/schemas/ContactFieldReference" }, "displayNameSource": { "$ref": "#/components/schemas/ContactFieldReference" }, "organizationSource": { "$ref": "#/components/schemas/ContactFieldReference" }, "contactNameSource": { "$ref": "#/components/schemas/ContactFieldReference" }, "notesSource": { "$ref": "#/components/schemas/ContactFieldReference" }, "defaultRegion": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, "ContactTransferReviewChange": { "type": "object", "additionalProperties": false, "required": [ "candidateId", "selected" ], "properties": { "candidateId": { "type": "string", "format": "uuid" }, "selected": { "type": "boolean" }, "displayName": { "type": [ "string", "null" ], "maxLength": 160 }, "organization": { "type": [ "string", "null" ], "maxLength": 160 }, "contactName": { "type": [ "string", "null" ], "maxLength": 160 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "ContactTransferReviewCommand": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "generation", "changes" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "generation": { "type": "integer", "minimum": 1, "maximum": 10000 }, "changes": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "$ref": "#/components/schemas/ContactTransferReviewChange" } } } }, "ContactTransferConfirmCommand": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "generation", "reviewRevision" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "generation": { "type": "integer", "minimum": 1, "maximum": 10000 }, "reviewRevision": { "type": "integer", "minimum": 0, "maximum": 10000 } } }, "ContactTransferVersionCommand": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 1 } } }, "ContactTransferExportRequest": { "type": "object", "additionalProperties": false, "required": [ "profile", "includeActive", "includeDeleted", "contractVersion" ], "properties": { "profile": { "type": "string", "enum": [ "portable_csv", "faximus_backup_csv", "vcard" ] }, "includeActive": { "type": "boolean" }, "includeDeleted": { "type": "boolean" }, "contractVersion": { "type": "string", "const": "contact-transfer.v2" } }, "example": { "profile": "portable_csv", "includeActive": true, "includeDeleted": false, "contractVersion": "contact-transfer.v2" } }, "ContactTransferCounts": { "type": "object", "additionalProperties": false, "required": [ "sourceContacts", "candidates", "selected", "created", "skipped", "invalid" ], "properties": { "sourceContacts": { "type": "integer", "minimum": 0, "maximum": 10000 }, "candidates": { "type": "integer", "minimum": 0, "maximum": 20000 }, "selected": { "type": "integer", "minimum": 0, "maximum": 20000 }, "created": { "type": "integer", "minimum": 0, "maximum": 20000 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 20000 }, "invalid": { "type": "integer", "minimum": 0, "maximum": 20000 } } }, "ContactTransferCapabilities": { "type": "object", "additionalProperties": false, "required": [ "canUpload", "canEditMapping", "canReview", "canConfirm", "canCancel", "canRetry", "canDownload" ], "properties": { "canUpload": { "type": "boolean" }, "canEditMapping": { "type": "boolean" }, "canReview": { "type": "boolean" }, "canConfirm": { "type": "boolean" }, "canCancel": { "type": "boolean" }, "canRetry": { "type": "boolean" }, "canDownload": { "type": "boolean" } } }, "ContactTransfer": { "type": "object", "additionalProperties": false, "required": [ "transferId", "kind", "version", "state", "sourceFormat", "exportFormat", "mappingRevision", "generation", "reviewRevision", "mappingPrompt", "counts", "reasonCode", "capabilities", "createdAt", "updatedAt", "completedAt" ], "properties": { "transferId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "import", "export" ] }, "version": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "uploading", "exporting", "analyzing", "mapping_required", "ready_for_review", "confirming", "complete", "failed", "cancelled", "expired" ] }, "sourceFormat": { "type": [ "string", "null" ], "enum": [ "faximus_csv_v1", "faximus_backup_csv_v1", "google_contacts_csv", "outlook_contacts_csv", "generic_csv", "vcard_3", "vcard_4", null ] }, "exportFormat": { "type": [ "string", "null" ], "enum": [ "portable_csv", "faximus_backup_csv", "vcard", null ] }, "mappingRevision": { "type": "integer", "minimum": 0, "maximum": 10000 }, "generation": { "type": "integer", "minimum": 0, "maximum": 10000 }, "reviewRevision": { "type": "integer", "minimum": 0, "maximum": 10000 }, "mappingPrompt": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "schemaVersion", "sourceDigest", "adapterVersion", "mappingVersion", "headers" ], "properties": { "schemaVersion": { "type": "string", "const": "contact-field-mapping-prompt.v1" }, "sourceDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "adapterVersion": { "type": "string", "const": "generic-contact-csv.v1" }, "mappingVersion": { "type": "integer", "minimum": 1, "maximum": 10000 }, "headers": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": [ "position", "name", "normalizedName" ], "properties": { "position": { "type": "integer", "minimum": 0, "maximum": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "normalizedName": { "type": "string", "minLength": 1, "maxLength": 512 } } } } } }, "counts": { "$ref": "#/components/schemas/ContactTransferCounts" }, "reasonCode": { "type": [ "string", "null" ], "pattern": "^[a-z][a-z0-9_]{0,95}$" }, "capabilities": { "$ref": "#/components/schemas/ContactTransferCapabilities" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ContactTransferCandidate": { "type": "object", "additionalProperties": false, "required": [ "candidateId", "ordinal", "displayName", "faxNumber", "organization", "contactName", "notes", "sourceLabel", "selected", "classification", "reasonCode" ], "properties": { "candidateId": { "type": "string", "format": "uuid" }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 20000 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "faxNumber": { "type": [ "string", "null" ], "maxLength": 64 }, "organization": { "type": [ "string", "null" ], "maxLength": 160 }, "contactName": { "type": [ "string", "null" ], "maxLength": 160 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "sourceLabel": { "type": [ "string", "null" ], "maxLength": 160 }, "selected": { "type": "boolean" }, "classification": { "type": "string", "enum": [ "ready", "exact_duplicate", "same_number", "excluded", "invalid" ] }, "reasonCode": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,95}$" } } }, "ContactTransferCandidatePage": { "type": "object", "additionalProperties": false, "required": [ "items", "pageSize", "nextCursor" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ContactTransferCandidate" } }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 2048 } } }, "ContactTransferArtifact": { "type": "object", "additionalProperties": false, "required": [ "downloadUrl", "expiresAt", "contentType", "fileName" ], "properties": { "downloadUrl": { "type": "string", "format": "uri", "maxLength": 4096, "description": "Short-lived private exact-version URL; never log or persist it." }, "expiresAt": { "type": "string", "format": "date-time" }, "contentType": { "type": "string", "enum": [ "text/csv", "text/vcard" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "CommercialContactRequest": { "type": "object", "additionalProperties": false, "required": [ "companyName", "contactEmail", "intent", "captchaToken" ], "properties": { "companyName": { "type": "string", "minLength": 1, "maxLength": 160, "example": "Example Health Group" }, "contactName": { "type": "string", "maxLength": 160, "example": "Jordan Smith" }, "contactEmail": { "type": "string", "format": "email", "maxLength": 254, "example": "jordan@example.com" }, "phoneE164": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$", "example": "+15551234567" }, "intent": { "type": "string", "maxLength": 280, "example": "Need programmable outbound and inbound fax for claims workflows." }, "captchaProvider": { "type": "string", "enum": [ "aws_waf_captcha" ], "default": "aws_waf_captcha" }, "captchaToken": { "type": "string", "minLength": 8, "maxLength": 4096, "description": "One-time anti-abuse token for the submitted form. It is not stored as a reusable secret." } } }, "CommercialOnboardingStartRequest": { "type": "object", "additionalProperties": false, "required": [ "planKey", "contactEmail", "acceptedLegalDocumentIds", "captchaToken" ], "properties": { "planKey": { "type": "string", "minLength": 3, "maxLength": 64, "example": "starter" }, "contactEmail": { "type": "string", "format": "email", "maxLength": 254, "example": "admin@example.com" }, "acceptedLegalDocumentIds": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uuid" } }, "captchaToken": { "type": "string", "minLength": 8, "maxLength": 4096, "description": "One-time anti-abuse token for signup initiation. It is not stored as a reusable secret." } } }, "CommercialPricingPlanPreview": { "type": "object", "additionalProperties": false, "required": [ "planKey", "displayName", "billingInterval", "currencyCode", "unitAmountCents", "includedUnits", "effectiveAt" ], "properties": { "planKey": { "type": "string", "example": "starter" }, "displayName": { "type": "string", "example": "Starter" }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual", "usage" ] }, "currencyCode": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" }, "unitAmountCents": { "type": "integer", "minimum": 0, "example": 4900 }, "includedUnits": { "type": "integer", "minimum": 0, "example": 500 }, "featureLabels": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 120 } }, "effectiveAt": { "type": "string", "format": "date-time" } } }, "ApiKey": { "type": "object", "required": [ "apiKeyId", "tenantId", "name", "keyPrefix", "scopeSet", "environment", "status", "createdAt", "updatedAt" ], "properties": { "apiKeyId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Claims fax integration" }, "keyPrefix": { "type": "string", "description": "Safe prefix used to identify the key without exposing secret material.", "example": "D-APalYY" }, "scopeSet": { "type": "array", "items": { "$ref": "#/components/schemas/ApiScope" } }, "environment": { "type": "string", "enum": [ "nonprod", "sandbox", "production" ] }, "status": { "type": "string", "enum": [ "active", "revoked", "disabled" ] }, "lastUsedAt": { "type": [ "null", "string" ], "format": "date-time" }, "createdBy": { "type": "string" }, "revokedAt": { "type": [ "null", "string" ], "format": "date-time" }, "disabledAt": { "type": [ "null", "string" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ApiKeyListResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "ApiKeyResponse": { "type": "object", "required": [ "apiKey" ], "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKey" }, "event": { "type": "string" } } }, "ApiRootResponse": { "type": "object", "required": [ "service", "environment", "version", "requestId", "links" ], "properties": { "service": { "type": "string", "example": "faximus-api" }, "environment": { "type": "string", "example": "production" }, "version": { "type": "string", "example": "0.1.0" }, "requestId": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "ApiScope": { "type": "string", "enum": [ "fax:send", "fax:read", "fax:delete", "webhook:manage", "did:manage", "usage:read", "admin:tenant", "phonebook:read", "phonebook:write" ] }, "Contact": { "type": "object", "properties": { "firstName": { "type": [ "null", "string" ] }, "lastName": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "phoneNumber": { "type": [ "null", "string" ], "pattern": "^\\+[1-9][0-9]{1,14}$" }, "companyName": { "type": [ "null", "string" ] }, "address": { "type": "object", "properties": { "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "region": { "type": [ "null", "string" ] }, "postalCode": { "type": [ "null", "string" ] }, "country": { "type": [ "null", "string" ] } } } } }, "CoverPage": { "type": "object", "required": [ "coverPageId", "documentId", "status" ], "properties": { "coverPageId": { "type": "string", "format": "uuid" }, "documentId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": [ "null", "integer" ] }, "pageCount": { "type": [ "null", "integer" ] }, "pageAccountingStatus": { "type": [ "null", "string" ] }, "checksumPresent": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CoverPageResponse": { "type": "object", "required": [ "event", "coverPage" ], "properties": { "event": { "type": "string", "example": "customer_cover_page_readback" }, "coverPage": { "anyOf": [ { "$ref": "#/components/schemas/CoverPage" }, { "type": "null" } ] } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name", "scopeSet" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "type": "string", "enum": [ "nonprod", "sandbox", "production" ], "default": "production", "description": "Defaults to production on the supported production deployment. Historical environment labels do not select isolated test behavior." }, "scopeSet": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ApiScope" } } } }, "CreateApiKeyResponse": { "type": "object", "required": [ "apiKey", "plaintextKey" ], "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKey" }, "plaintextKey": { "type": "string", "description": "Shown once. Store it before closing the response. Format is fxk___; an environment label does not guarantee isolated test behavior.", "example": "fxk_production_D-APalYY_redactedExampleOnly" } } }, "CreateCustomerWebhookEndpointRequest": { "type": "object", "required": [ "url", "eventTypes" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://hooks.example.test/fax" }, "safeLabel": { "type": "string", "maxLength": 128, "example": "Primary delivery hook" }, "eventTypes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEventType" } } } }, "CreateDocumentRequest": { "type": "object", "required": [ "fileName", "contentType" ], "properties": { "fileName": { "type": "string", "maxLength": 255, "example": "claim-form.pdf" }, "contentType": { "type": "string", "enum": [ "application/pdf" ] }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 26214400 }, "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" } } }, "CreateDocumentResponse": { "type": "object", "required": [ "documentId", "uploadUrl", "uploadFields", "expiresAt", "completeUrl" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string", "format": "uri" }, "uploadFields": { "type": "object", "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" }, "completeUrl": { "type": "string" } } }, "CreateFaxJobRequest": { "type": "object", "required": [ "destinationNumber", "senderIdentity", "documents" ], "properties": { "destinationNumber": { "type": "string", "description": "Destination fax number in E.164 format.", "pattern": "^\\+[1-9][0-9]{1,14}$", "example": "+15551234567" }, "senderIdentity": { "type": "string", "description": "Active sending fax number assigned to the caller's account.", "pattern": "^\\+[1-9][0-9]{1,14}$", "example": "+18643106131" }, "documents": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "documentId" ], "properties": { "documentId": { "type": "string", "format": "uuid" } } } }, "correlationId": { "type": "string", "maxLength": 128 }, "includeDefaultCoverPage": { "type": "boolean", "default": false }, "highResolutionColorCopy": { "type": "boolean", "default": false, "description": "Optional paid-plan recipient access copy. When true, Faximus sends the normal fax, prepends secure access instructions, stores the original submitted file privately, and expires recipient access automatically." }, "metadata": { "type": "object", "additionalProperties": true } } }, "CustomerAccountActivityLinked": { "type": "object", "additionalProperties": true, "properties": { "accountId": { "type": [ "null", "string" ], "format": "uuid" }, "tenantId": { "type": [ "null", "string" ], "format": "uuid" }, "faxJobId": { "type": [ "null", "string" ], "format": "uuid" }, "inboundFaxId": { "type": [ "null", "string" ], "format": "uuid" }, "emailGatewayMessageId": { "type": [ "null", "string" ], "format": "uuid" }, "direction": { "type": [ "null", "string" ], "enum": [ "email_to_fax", "fax_to_email", null ] }, "portRequestId": { "type": [ "null", "string" ], "format": "uuid" }, "loaDocumentId": { "type": [ "null", "string" ], "format": "uuid" }, "documentId": { "type": [ "null", "string" ], "format": "uuid" }, "cartId": { "type": [ "null", "string" ], "format": "uuid" }, "packageCode": { "type": [ "null", "string" ] }, "correlationId": { "type": [ "null", "string" ] } } }, "CustomerAccountActivityFilters": { "type": "object", "description": "Customer-safe lookup filters that product surfaces can use to reopen related activity.", "additionalProperties": false, "properties": { "category": { "type": "string", "enum": [ "account", "billing", "loa", "number_transfer", "email_fax", "fax_delivery", "inbox" ] }, "requestId": { "type": "string", "maxLength": 256 }, "correlationId": { "type": "string", "maxLength": 128 }, "reasonCode": { "type": "string", "maxLength": 128 }, "direction": { "type": "string", "enum": [ "email_to_fax", "fax_to_email" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } }, "CustomerAccountActivityItem": { "type": "object", "required": [ "activityId", "category", "type", "title", "message", "nextAction", "occurredAt", "linked", "activityFilters", "supportSummary", "source" ], "properties": { "activityId": { "type": "string", "description": "Stable source-qualified activity identifier." }, "category": { "type": "string", "enum": [ "account", "billing", "loa", "number_transfer", "email_fax", "fax_delivery", "inbox" ] }, "type": { "type": "string", "example": "email_fax.message" }, "title": { "type": "string", "example": "Attachment needed" }, "message": { "type": "string", "example": "No supported fax attachment was found." }, "nextAction": { "type": "string", "example": "Attach a PDF or supported document and send again." }, "status": { "type": [ "null", "string" ] }, "statusLabel": { "type": [ "null", "string" ] }, "tone": { "type": "string", "enum": [ "neutral", "info", "success", "warning" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "requestId": { "type": [ "null", "string" ] }, "linked": { "$ref": "#/components/schemas/CustomerAccountActivityLinked" }, "activityFilters": { "$ref": "#/components/schemas/CustomerAccountActivityFilters" }, "supportSummary": { "type": "string", "description": "Customer-safe summary suitable for support handoff." }, "source": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "CustomerAccountActivityResponse": { "type": "object", "required": [ "event", "tenantId", "accountId", "category", "limit", "items", "resultTruncated", "scannedCount" ], "properties": { "event": { "type": "string", "example": "customer_account_activity" }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "category": { "type": [ "null", "string" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountActivityItem" } }, "nextCursor": { "type": [ "null", "string" ] }, "resultTruncated": { "type": "boolean" }, "scannedCount": { "type": "integer", "minimum": 0 } } }, "CustomerAccountProfileResponse": { "type": "object", "required": [ "event", "tenant", "account", "membership", "sessionPolicy" ], "properties": { "event": { "type": "string", "example": "customer_account_profile" }, "tenant": { "type": "object", "required": [ "tenantId", "tenantType", "name", "status" ], "properties": { "tenantId": { "type": "string", "format": "uuid" }, "externalReference": { "type": [ "null", "string" ] }, "tenantType": { "type": "string", "example": "customer" }, "name": { "type": "string" }, "status": { "type": "string" } } }, "account": { "type": "object", "required": [ "accountId", "displayName", "status" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "status": { "type": "string" } } }, "membership": { "type": "object", "properties": { "role": { "type": "string" }, "tenantRole": { "type": "string" }, "subject": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "emailVerified": { "type": "boolean" }, "displayName": { "type": [ "null", "string" ] }, "contact": { "$ref": "#/components/schemas/Contact" } } }, "sessionPolicy": { "$ref": "#/components/schemas/CustomerAccountSessionPolicy" } } }, "CustomerAccountUserRole": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "CustomerAccountUser": { "type": "object", "required": [ "subject", "role", "active", "status", "isCurrentUser" ], "properties": { "subject": { "type": "string", "description": "Cognito subject for this workspace user." }, "email": { "type": [ "null", "string" ], "format": "email" }, "displayName": { "type": [ "null", "string" ] }, "role": { "$ref": "#/components/schemas/CustomerAccountUserRole" }, "active": { "type": "boolean" }, "status": { "type": "string", "example": "active" }, "isCurrentUser": { "type": "boolean" }, "updatedAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "CustomerUserInvitation": { "type": "object", "required": [ "invitationId", "email", "role", "status", "expiresAt", "createdAt" ], "properties": { "invitationId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "displayName": { "type": [ "null", "string" ] }, "role": { "$ref": "#/components/schemas/CustomerAccountUserRole" }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": [ "null", "string" ], "format": "date-time" }, "revokedAt": { "type": [ "null", "string" ], "format": "date-time" }, "delivery": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "sent", "failed" ] } } } } }, "CustomerAccountUsersResponse": { "type": "object", "required": [ "event", "accountId", "tenantId", "currentUserRole", "permissions", "users", "invitations" ], "properties": { "event": { "type": "string", "example": "customer_account_users" }, "accountId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "currentUserRole": { "$ref": "#/components/schemas/CustomerAccountUserRole" }, "permissions": { "type": "object", "required": [ "canInvite", "canManage", "canManageOwners" ], "properties": { "canInvite": { "type": "boolean" }, "canManage": { "type": "boolean" }, "canManageOwners": { "type": "boolean" } } }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountUser" } }, "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerUserInvitation" } } } }, "CustomerAccountUserResponse": { "type": "object", "required": [ "event", "user" ], "properties": { "event": { "type": "string", "example": "customer_team_user_updated" }, "user": { "$ref": "#/components/schemas/CustomerAccountUser" } } }, "CustomerUserInvitationResponse": { "type": "object", "required": [ "event", "invitation" ], "properties": { "event": { "type": "string", "example": "customer_team_invitation_revoked" }, "invitation": { "$ref": "#/components/schemas/CustomerUserInvitation" } } }, "CustomerUserInvitationCreatedResponse": { "allOf": [ { "$ref": "#/components/schemas/CustomerUserInvitationResponse" }, { "type": "object", "required": [ "delivery", "acceptUrlConfigured" ], "properties": { "delivery": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "example": "sent" }, "reason": { "type": "string" } } }, "acceptUrlConfigured": { "type": "boolean" } } } ] }, "CustomerUserInvitationResentResponse": { "allOf": [ { "$ref": "#/components/schemas/CustomerUserInvitationCreatedResponse" }, { "type": "object", "required": [ "idempotentReplay" ], "properties": { "event": { "type": "string", "enum": [ "customer_team_invitation_resent", "customer_team_invitation_resend_in_progress" ] }, "delivery": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "sent", "failed" ] }, "retryable": { "type": "boolean" } } }, "idempotentReplay": { "type": "boolean" } } } ] }, "CustomerUserInvitationPreviewResponse": { "type": "object", "required": [ "event", "invitation" ], "properties": { "event": { "type": "string", "example": "customer_team_invitation" }, "invitation": { "$ref": "#/components/schemas/CustomerUserInvitation" }, "workspaceName": { "type": [ "null", "string" ] } } }, "CustomerUserInvitationAcceptedResponse": { "allOf": [ { "$ref": "#/components/schemas/CustomerUserInvitationResponse" }, { "type": "object", "required": [ "accountId", "tenantId" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "workspaceName": { "type": [ "null", "string" ] } } } ] }, "CreateCustomerUserInvitationRequest": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "displayName": { "type": [ "null", "string" ], "maxLength": 128 }, "role": { "$ref": "#/components/schemas/CustomerAccountUserRole" } } }, "PatchCustomerAccountUserRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "role": { "$ref": "#/components/schemas/CustomerAccountUserRole" }, "displayName": { "type": [ "null", "string" ], "maxLength": 128 }, "isActive": { "type": "boolean" } } }, "BillingHistoryPage": { "type": "object", "additionalProperties": false, "required": [ "hasMore", "nextCursor" ], "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "null", "string" ], "maxLength": 512 } } }, "BillingUsagePeriod": { "type": "object", "additionalProperties": false, "required": [ "periodStart", "periodEnd", "totalPages", "includedPages", "overagePages", "overageAmountCents", "currencyCode" ], "properties": { "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "totalPages": { "type": "number", "minimum": 0 }, "includedPages": { "type": "number", "minimum": 0 }, "overagePages": { "type": "number", "minimum": 0 }, "overageAmountCents": { "type": "integer", "minimum": 0 }, "currencyCode": { "type": [ "null", "string" ], "pattern": "^[A-Z]{3}$" } } }, "BillingInvoice": { "type": "object", "additionalProperties": false, "required": [ "invoiceId", "invoiceNumber", "status", "createdAt", "dueAt", "paidAt", "periodStart", "periodEnd", "subtotalCents", "totalCents", "amountDueCents", "amountPaidCents", "amountRemainingCents", "currencyCode", "hostedInvoiceUrl", "invoicePdfUrl" ], "properties": { "invoiceId": { "type": "string", "pattern": "^in_[A-Za-z0-9]+$" }, "invoiceNumber": { "type": [ "null", "string" ], "maxLength": 128 }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "uncollectible", "void" ] }, "createdAt": { "type": [ "null", "string" ], "format": "date-time" }, "dueAt": { "type": [ "null", "string" ], "format": "date-time" }, "paidAt": { "type": [ "null", "string" ], "format": "date-time" }, "periodStart": { "type": [ "null", "string" ], "format": "date-time" }, "periodEnd": { "type": [ "null", "string" ], "format": "date-time" }, "subtotalCents": { "type": "integer" }, "totalCents": { "type": "integer" }, "amountDueCents": { "type": "integer" }, "amountPaidCents": { "type": "integer" }, "amountRemainingCents": { "type": "integer" }, "currencyCode": { "type": [ "null", "string" ], "pattern": "^[A-Z]{3}$" }, "hostedInvoiceUrl": { "type": [ "null", "string" ], "format": "uri" }, "invoicePdfUrl": { "type": [ "null", "string" ], "format": "uri" } } }, "BillingTransaction": { "type": "object", "additionalProperties": false, "required": [ "transactionId", "invoiceId", "status", "createdAt", "amountCents", "amountRefundedCents", "currencyCode", "receiptUrl" ], "properties": { "transactionId": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$" }, "invoiceId": { "type": [ "null", "string" ], "pattern": "^in_[A-Za-z0-9]+$" }, "status": { "type": "string", "enum": [ "succeeded", "pending", "failed", "partially_refunded", "refunded" ] }, "createdAt": { "type": [ "null", "string" ], "format": "date-time" }, "amountCents": { "type": "integer", "minimum": 0 }, "amountRefundedCents": { "type": "integer", "minimum": 0 }, "currencyCode": { "type": [ "null", "string" ], "pattern": "^[A-Z]{3}$" }, "receiptUrl": { "type": [ "null", "string" ], "format": "uri" } } }, "CommercialBillingHistoryResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "tenantId", "accountId", "providerCustomerConfigured", "providerStatus", "usagePeriods", "invoices", "transactions", "pagination" ], "properties": { "event": { "type": "string", "enum": [ "commercial_billing_history" ] }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "providerCustomerConfigured": { "type": "boolean" }, "providerStatus": { "type": "string", "enum": [ "ready", "not_configured", "unavailable" ] }, "usagePeriods": { "type": "array", "items": { "$ref": "#/components/schemas/BillingUsagePeriod" } }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/BillingInvoice" } }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/BillingTransaction" } }, "pagination": { "type": "object", "additionalProperties": false, "required": [ "limit", "usage", "invoices", "transactions" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "usage": { "$ref": "#/components/schemas/BillingHistoryPage" }, "invoices": { "$ref": "#/components/schemas/BillingHistoryPage" }, "transactions": { "$ref": "#/components/schemas/BillingHistoryPage" } } } } }, "BillingUsageResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "tenantId", "accountId", "faxPages", "items" ], "properties": { "event": { "type": "string", "enum": [ "commercial_billing_usage" ] }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "period": { "type": [ "null", "object" ], "additionalProperties": false, "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "faxPages": { "type": "object", "additionalProperties": false, "required": [ "totalPages", "includedAllowance", "includedPages", "overagePages", "overageUnitAmountCents", "projectedOverageAmountCents" ], "properties": { "packageCode": { "type": [ "null", "string" ] }, "totalPages": { "type": "number" }, "billingRatingQualified": { "type": "boolean", "description": "False when recorded page quantities are available but accepted rating terms need review. Included usage, overage quantities and amounts are then null; a known accepted access allowance may still be shown." }, "includedAllowance": { "type": [ "number", "null" ] }, "includedPages": { "type": [ "number", "null" ] }, "overagePages": { "type": [ "number", "null" ] }, "overageUnitAmountCents": { "type": [ "integer", "null" ] }, "projectedOverageAmountCents": { "type": [ "integer", "null" ] }, "currencyCode": { "type": "string", "example": "USD" }, "providerReportingConfigured": { "type": "boolean" } } }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "usageType": { "type": "string", "example": "fax_pages" }, "unit": { "type": "string", "example": "page" }, "reportedStatus": { "type": "string", "enum": [ "pending", "reported", "skipped", "failed" ] }, "direction": { "type": [ "null", "string" ], "enum": [ "inbound", "outbound", null ] }, "quantity": { "type": "number" }, "includedQuantity": { "type": [ "number", "null" ] }, "chargeableQuantity": { "type": [ "number", "null" ] }, "overageAmountCents": { "type": [ "integer", "null" ] } } } } } }, "CustomerDid": { "type": "object", "required": [ "didId", "didE164" ], "properties": { "didId": { "type": "string", "format": "uuid" }, "didE164": { "type": "string", "example": "+18643106131" }, "label": { "type": [ "null", "string" ] }, "usageType": { "type": "string" }, "inboundEnabled": { "type": "boolean" }, "outboundEnabled": { "type": "boolean" } } }, "CustomerDidResponse": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/CustomerDid" } } }, "CustomerDidsResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerDid" } } } }, "SenderIdentity": { "type": "object", "additionalProperties": false, "required": [ "id", "didId", "didE164", "source", "sendAllowed", "receiveAllowed" ], "properties": { "id": { "type": "string" }, "didId": { "type": "string", "format": "uuid" }, "didE164": { "type": "string", "example": "+18647626276" }, "label": { "type": [ "null", "string" ] }, "source": { "type": "string", "enum": [ "assigned_did", "developer_shared" ] }, "sendAllowed": { "type": "boolean" }, "receiveAllowed": { "type": "boolean" } } }, "SenderIdentitiesResponse": { "type": "object", "additionalProperties": true, "required": [ "items" ], "properties": { "packageTier": { "type": [ "null", "string" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SenderIdentity" } } } }, "CustomerInboxItem": { "type": "object", "additionalProperties": true, "required": [ "inboundFaxId" ], "properties": { "inboundFaxId": { "type": "string", "format": "uuid" }, "importState": { "type": "string" }, "receivedAt": { "type": [ "null", "string" ], "format": "date-time" }, "callerIdE164": { "type": [ "null", "string" ] }, "calledDidE164": { "type": [ "null", "string" ] }, "pageCount": { "type": [ "null", "integer" ] }, "document": { "type": "object", "additionalProperties": true } } }, "CustomerInboxResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerInboxItem" } }, "nextCursor": { "type": [ "null", "string" ] } } }, "EmailFaxDomain": { "type": "object", "additionalProperties": true, "required": [ "domainId", "domainName", "verificationStatus" ], "properties": { "domainId": { "type": "string", "format": "uuid" }, "domainName": { "type": "string", "example": "example.com" }, "verificationStatus": { "type": "string", "enum": [ "pending", "verified", "failed", "disabled" ] }, "verificationMethod": { "type": "string", "example": "dns_txt" }, "verificationRecordName": { "type": "string", "example": "_faximus.example.com" }, "verificationRecordValue": { "type": "string", "example": "faximus-verify=abc123" }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "disabledAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "EmailFaxPreferences": { "type": "object", "additionalProperties": true, "required": [ "faxToEmail", "emailToFax" ], "properties": { "faxToEmail": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean" }, "deliveryMode": { "type": "string", "enum": [ "link_only", "attach_pdf" ] }, "attachPdf": { "type": "boolean" } } }, "emailToFax": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean" }, "senderSelection": { "$ref": "#/components/schemas/EmailFaxSenderSelection" } } } } }, "EmailFaxSenderBinding": { "type": "object", "additionalProperties": false, "required": [ "senderIdentity" ], "properties": { "bindingId": { "type": "string" }, "bindingType": { "type": "string", "enum": [ "account_default", "domain_default", "source_email" ] }, "sourceEmail": { "type": [ "null", "string" ], "format": "email" }, "sourceDomain": { "type": [ "null", "string" ] }, "senderIdentity": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" }, "disabledAt": { "type": [ "null", "string" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EmailFaxSenderSelection": { "type": "object", "additionalProperties": false, "properties": { "accountDefaultSenderIdentity": { "type": [ "null", "string" ], "pattern": "^\\+[1-9][0-9]{7,14}$" }, "domainDefaultSenderBindings": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxSenderBinding" } }, "sourceEmailSenderBindings": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxSenderBinding" } } } }, "EmailFaxMessage": { "type": "object", "additionalProperties": false, "properties": { "messageId": { "type": "string", "format": "uuid" }, "direction": { "type": [ "null", "string" ] }, "inboundFaxId": { "type": [ "null", "string" ], "format": "uuid" }, "submissionMethod": { "type": "string" }, "requestId": { "type": [ "null", "string" ] }, "display": { "type": "object", "additionalProperties": false, "properties": { "statusText": { "type": "string" }, "message": { "type": "string" }, "nextAction": { "type": "string" } } }, "messageStatus": { "type": "string" }, "rejectionCode": { "type": [ "null", "string" ] }, "sourceEmail": { "type": [ "null", "string" ], "format": "email" }, "sourceDomain": { "type": [ "null", "string" ] }, "destinationEmail": { "type": [ "null", "string" ] }, "destinationNumber": { "type": [ "null", "string" ] }, "selectedSenderIdentity": { "type": [ "null", "string" ] }, "selectedSenderSource": { "type": [ "null", "string" ] }, "terminalDeliveryState": { "type": [ "null", "string" ] }, "faxJobId": { "type": [ "null", "string" ], "format": "uuid" }, "retryAttemptCount": { "description": "Current persisted fax attempt count. Capture this value when creating a retry intent and send it quoted in If-Match; keep the captured value unchanged when replaying that intent.", "type": [ "null", "integer" ], "minimum": 0, "maximum": 5 }, "receivedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "null", "string" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EmailFaxRecipient": { "type": "object", "additionalProperties": true, "required": [ "recipientId", "email", "recipientStatus" ], "properties": { "recipientId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "recipientStatus": { "type": "string", "enum": [ "pending", "verified", "disabled" ] }, "verificationSentAt": { "type": [ "null", "string" ], "format": "date-time" }, "verifiedAt": { "type": [ "null", "string" ], "format": "date-time" }, "disabledAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "EmailFaxSettingsResponse": { "type": "object", "additionalProperties": true, "required": [ "preferences", "acceptedEmailToFaxDomains", "sourceDomains", "recipients" ], "properties": { "preferences": { "$ref": "#/components/schemas/EmailFaxPreferences" }, "acceptedEmailToFaxDomains": { "type": "array", "items": { "type": "string" } }, "sourceDomains": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxDomain" } }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxRecipient" } }, "activity": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxMessage" } } } }, "EmailFaxPreferencesResponse": { "type": "object", "additionalProperties": true, "required": [ "preferences" ], "properties": { "preferences": { "$ref": "#/components/schemas/EmailFaxPreferences" } } }, "EmailFaxMessagesResponse": { "type": "object", "additionalProperties": true, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxMessage" } }, "limit": { "type": "integer" } } }, "EmailFaxRetryResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "messageId", "faxJobId", "retry" ], "properties": { "event": { "const": "customer_email_fax_message_retry" }, "messageId": { "type": "string", "format": "uuid" }, "faxJobId": { "type": "string", "format": "uuid" }, "retry": { "type": "object", "additionalProperties": false, "required": [ "newStatus", "retryPolicyVersion", "previousAttemptCount", "correlationId" ], "properties": { "newStatus": { "const": "queued" }, "retryPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "previousAttemptCount": { "type": "integer", "minimum": 1, "maximum": 4 }, "correlationId": { "type": [ "string", "null" ], "maxLength": 128 } } } } }, "EmailFaxDomainsResponse": { "type": "object", "additionalProperties": true, "required": [ "sourceDomains" ], "properties": { "sourceDomains": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxDomain" } } } }, "EmailFaxDomainResponse": { "type": "object", "additionalProperties": true, "required": [ "sourceDomain" ], "properties": { "sourceDomain": { "$ref": "#/components/schemas/EmailFaxDomain" } } }, "EmailFaxRecipientsResponse": { "type": "object", "additionalProperties": true, "required": [ "recipients" ], "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/EmailFaxRecipient" } } } }, "EmailFaxRecipientResponse": { "type": "object", "additionalProperties": true, "required": [ "recipient" ], "properties": { "recipient": { "$ref": "#/components/schemas/EmailFaxRecipient" }, "verification": { "type": "object", "additionalProperties": true } } }, "CustomerUsageSummaryResponse": { "type": "object", "additionalProperties": true, "required": [ "event", "from", "to", "items" ], "properties": { "event": { "type": "string", "example": "customer_usage_summary" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "CustomerWebhookEndpoint": { "type": "object", "required": [ "endpointId", "url", "status", "eventTypes" ], "properties": { "endpointId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "urlRedacted": { "type": "string" }, "safeLabel": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "disabled", "deleted" ] }, "eventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "signingSecret": { "type": "string", "description": "Present only in the create response." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "disabledAt": { "type": [ "null", "string" ], "format": "date-time" }, "deletedAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "CustomerWebhookEndpointListResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerWebhookEndpoint" } } } }, "CustomerWebhookEndpointResponse": { "type": "object", "required": [ "event", "endpoint" ], "properties": { "event": { "type": "string" }, "endpoint": { "$ref": "#/components/schemas/CustomerWebhookEndpoint" } } }, "DeliveryState": { "type": "string", "enum": [ "confirmed", "failed", "unconfirmed", "delivery_confirmed", "delivery_failed", "delivery_unconfirmed", "evidence_incomplete", "not_attempted", "pending" ] }, "DependencyCheck": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pass", "fail" ] }, "code": { "type": "string" }, "latencyMs": { "type": "number" } } }, "Document": { "type": "object", "required": [ "documentId" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": [ "null", "integer" ] }, "pageCount": { "type": [ "null", "integer" ] }, "pageAccountingStatus": { "type": [ "null", "string" ] }, "checksumPresent": { "type": "boolean" }, "canPreview": { "type": "boolean" }, "canDownload": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "DocumentAccessResponse": { "type": "object", "additionalProperties": true, "required": [ "documentAccessUrl" ], "properties": { "documentAccessUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "filename": { "type": "string" }, "contentType": { "type": "string" } } }, "DocumentPreviewResponse": { "type": "object", "additionalProperties": true, "properties": { "previewPages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "fallbackPreview": { "type": "object", "additionalProperties": true } } }, "DocumentResponse": { "type": "object", "additionalProperties": true, "required": [ "documentId", "status" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_upload", "uploaded", "attached", "failed" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": [ "null", "integer" ] }, "completeUrl": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "missing_idempotency_key", "insufficient_scope", "account_selection_required" ] }, "message": { "type": "string" } } }, "requestId": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "FaxJob": { "type": "object", "additionalProperties": true, "required": [ "jobId", "status", "createdAt", "updatedAt", "statusUrl" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/FaxJobStatus" }, "canonicalState": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "statusUrl": { "type": "string" }, "destinationNumber": { "type": [ "null", "string" ] }, "senderIdentity": { "type": [ "null", "string" ] }, "documentCount": { "type": [ "null", "integer" ] }, "attemptCount": { "type": "integer" }, "resendAllowed": { "type": "boolean", "description": "Whether the original outcome permits customer Resend." }, "safetyStatus": { "type": "string", "enum": [ "confirming", "held", "exhausted", "retrying", "delivered", "failed" ], "description": "Customer-safe outcome and retry status; confirming or held prevents resend." }, "submissionMethod": { "type": "string", "enum": [ "unknown", "portal", "api", "email" ] }, "pageSummary": { "type": "object", "additionalProperties": true }, "correlationId": { "type": [ "null", "string" ] }, "delivery": { "$ref": "#/components/schemas/FaxJobDelivery" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "composedDocument": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": true } ] }, "highResolutionColorCopy": { "$ref": "#/components/schemas/HighResolutionFaxAccessSummary" } } }, "HighResolutionFaxAccessSummary": { "type": "object", "additionalProperties": false, "required": [ "enabled", "status", "expiresAt", "lastAccessedAt", "downloadCount" ], "properties": { "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "disabled", "active", "expired", "revoked" ] }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time" }, "lastAccessedAt": { "type": [ "null", "string" ], "format": "date-time" }, "downloadCount": { "type": "integer", "minimum": 0 } }, "description": "Safe high-resolution recipient access readback. This object never includes access tokens, passcodes, URLs, hashes, storage keys, or internal provider IDs." }, "FaxJobDelivery": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "description": "Customer-facing workflow status. Inspect state for authoritative confirmed, partial or uncertain delivery; unknown states must not be interpreted as success.", "example": "delivered" }, "state": { "$ref": "#/components/schemas/DeliveryState" }, "message": { "type": "string", "example": "Fax delivery confirmed." }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "pending", "none" ] }, "reasonCode": { "type": "string" }, "observedAt": { "type": [ "null", "string" ], "format": "date-time" }, "statusText": { "type": "string" }, "nextAction": { "type": "string" }, "statusHistory": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pageSummary": { "type": "object", "additionalProperties": true } } }, "FaxJobListResponse": { "type": "object", "required": [ "items" ], "properties": { "usageSummary": { "$ref": "#/components/schemas/OutboundPageUsageSummary" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FaxJob" } }, "nextCursor": { "type": [ "null", "string" ] } } }, "OutboundPageUsageSummary": { "type": "object", "required": [ "schemaVersion", "tenantId", "accountId", "asOf", "history", "rolling24Hours" ], "properties": { "schemaVersion": { "type": "string", "const": "faximus.outbound-page-usage.v1" }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "asOf": { "type": "string", "format": "date-time" }, "history": { "type": "object", "required": [ "from", "to", "timeZone", "days" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string", "const": "UTC" }, "days": { "type": "array", "minItems": 90, "maxItems": 90, "items": { "type": "object", "required": [ "from", "to", "submittedPages", "jobCount", "unknownJobCount" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "submittedPages": { "type": [ "integer", "null" ], "minimum": 0 }, "jobCount": { "type": "integer", "minimum": 0 }, "unknownJobCount": { "type": "integer", "minimum": 0 } } } } } }, "rolling24Hours": { "type": "object", "required": [ "from", "to", "countedPages", "unknownJobCount" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "countedPages": { "type": [ "integer", "null" ], "minimum": 0 }, "unknownJobCount": { "type": "integer", "minimum": 0 } } } } }, "FaxJobResponse": { "allOf": [ { "$ref": "#/components/schemas/FaxJob" } ] }, "FaxJobStatus": { "type": "string", "enum": [ "received", "queued", "rendering", "rendered", "processing", "dispatching", "retrying", "completed", "failed", "canceled", "dead_lettered" ] }, "PatchCustomerAccountProfileRequest": { "type": "object", "minProperties": 1, "properties": { "displayName": { "type": "string", "maxLength": 128 }, "firstName": { "type": [ "null", "string" ], "maxLength": 80 }, "lastName": { "type": [ "null", "string" ], "maxLength": 80 }, "title": { "type": [ "null", "string" ], "maxLength": 128 }, "companyName": { "type": [ "null", "string" ], "maxLength": 128 }, "phoneNumber": { "type": [ "null", "string" ], "pattern": "^\\+[1-9][0-9]{1,14}$" }, "address": { "type": "object", "properties": { "line1": { "type": [ "null", "string" ], "maxLength": 160 }, "line2": { "type": [ "null", "string" ], "maxLength": 160 }, "city": { "type": [ "null", "string" ], "maxLength": 96 }, "region": { "type": [ "null", "string" ], "maxLength": 96 }, "postalCode": { "type": [ "null", "string" ], "maxLength": 32 }, "country": { "type": [ "null", "string" ], "maxLength": 64 } } } } }, "CustomerAccountSessionPolicy": { "type": "object", "required": [ "ttlSeconds", "minTtlSeconds", "maxTtlSeconds", "effectiveExpiresAt" ], "properties": { "ttlSeconds": { "type": "integer", "minimum": 900, "maximum": 86400, "example": 14400 }, "minTtlSeconds": { "type": "integer", "example": 900 }, "maxTtlSeconds": { "type": "integer", "example": 86400 }, "effectiveExpiresAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "PatchCustomerAccountSessionPolicyRequest": { "type": "object", "required": [ "ttlSeconds" ], "additionalProperties": false, "properties": { "ttlSeconds": { "type": "integer", "minimum": 900, "maximum": 86400 } } }, "CustomerAccountSessionPolicyUpdateResponse": { "type": "object", "required": [ "event", "accountId", "tenantId", "sessionPolicy" ], "properties": { "event": { "type": "string", "example": "customer_account_session_policy_updated" }, "accountId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "sessionPolicy": { "$ref": "#/components/schemas/CustomerAccountSessionPolicy" } } }, "PatchCustomerWebhookEndpointRequest": { "type": "object", "minProperties": 1, "properties": { "url": { "type": "string", "format": "uri" }, "safeLabel": { "type": [ "null", "string" ], "maxLength": 128 }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "eventTypes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEventType" } } } }, "PatchEmailFaxSettingsRequest": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "faxToEmailEnabled": { "type": "boolean" }, "faxToEmailAttachPdf": { "type": "boolean" }, "emailToFaxEnabled": { "type": "boolean" }, "emailToFax": { "type": "object", "additionalProperties": true } } }, "CreateEmailFaxDomainRequest": { "type": "object", "additionalProperties": false, "required": [ "domainName" ], "properties": { "domainName": { "type": "string", "example": "example.com" } } }, "CreateEmailFaxRecipientRequest": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "records@example.com" } } }, "EmailFaxRecipientVerificationConfirmationRequest": { "type": "object", "additionalProperties": false, "required": [ "recipientId", "verificationToken" ], "properties": { "recipientId": { "type": "string", "format": "uuid" }, "verificationToken": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Unpadded base64url encoding of 32 random bytes, submitted only in the JSON request body." } } }, "EmailFaxRecipientVerificationSubmissionResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "requestId" ], "properties": { "event": { "type": "string", "const": "customer_email_fax_recipient_verification_submitted" }, "requestId": { "type": "string" } } }, "NumberSearchRequest": { "type": "object", "additionalProperties": false, "properties": { "searchType": { "type": "string", "enum": [ "area_code", "region", "exact" ], "default": "area_code" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "US" }, "region": { "type": "string", "maxLength": 64 }, "areaCode": { "type": "string", "pattern": "^[0-9]{3,6}$", "example": "864" }, "contains": { "type": "string", "maxLength": 16 }, "capabilityFilters": { "type": "array", "maxItems": 8, "items": { "type": "string", "maxLength": 32 }, "default": [ "fax" ] }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } }, "NumberCandidate": { "type": "object", "additionalProperties": false, "required": [ "candidateId", "candidateNumberE164", "countryCode", "capabilitySummary", "providerDomain", "providerCandidateRef", "availabilityStatus", "observedAt", "freshnessExpiresAt" ], "properties": { "candidateId": { "type": "string", "format": "uuid" }, "candidateNumberE164": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$", "example": "+18645551000" }, "countryCode": { "type": "string", "example": "US" }, "region": { "type": [ "null", "string" ] }, "locality": { "type": [ "null", "string" ] }, "capabilitySummary": { "type": "object", "additionalProperties": true, "description": "Sanitized capability summary; no raw provider payloads." }, "providerDomain": { "type": "string", "enum": [ "faximus" ] }, "providerCandidateRef": { "type": "string", "description": "Opaque provider candidate reference safe for support correlation." }, "monthlyAmountCents": { "type": [ "null", "integer" ] }, "currencyCode": { "type": [ "null", "string" ] }, "availabilityStatus": { "type": "string", "enum": [ "available", "unavailable", "unknown" ] }, "observedAt": { "type": "string", "format": "date-time" }, "freshnessExpiresAt": { "type": "string", "format": "date-time" }, "candidateFreshUntil": { "type": [ "null", "string" ], "format": "date-time" }, "activationStatus": { "type": "string", "enum": [ "available", "activating", "ready", "unavailable" ] }, "displayMessage": { "type": "string" }, "nextAction": { "type": "string" }, "sanitizedMetadata": { "type": "object", "additionalProperties": true } } }, "NumberSearchResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "tenantId", "accountId", "providerMode", "candidates" ], "properties": { "event": { "type": "string", "enum": [ "commercial_number_search" ] }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "requestId": { "type": "string" }, "providerMode": { "type": "string", "enum": [ "dry_run", "readback" ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/NumberCandidate" } } } }, "NumberReservationRequest": { "type": "object", "additionalProperties": false, "properties": { "candidateId": { "type": "string", "format": "uuid" }, "candidateNumberE164": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$", "example": "+18645551000" }, "requestedAreaCode": { "type": "string", "pattern": "^[0-9]{3,6}$" }, "onboardingSessionId": { "type": "string", "format": "uuid" }, "commercialCartId": { "type": "string", "format": "uuid" }, "packageCode": { "type": "string", "maxLength": 64, "default": "starter" }, "extraNumberBillingAccepted": { "type": "boolean", "default": false }, "expectedExtraNumberMonthlyAmountCents": { "type": [ "null", "integer" ], "enum": [ null, 300 ] } } }, "NumberReservation": { "type": "object", "additionalProperties": false, "required": [ "reservationId", "tenantId", "accountId", "reservationStatus", "providerOwnershipClaimed", "ttlExpiresAt", "customerSafeStatus" ], "properties": { "reservationId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "candidateNumberE164": { "type": [ "null", "string" ], "pattern": "^\\+[1-9][0-9]{7,14}$" }, "requestedAreaCode": { "type": [ "null", "string" ] }, "reservationStatus": { "type": "string", "enum": [ "reserved_intent", "expired", "approval_required", "purchase_pending", "provider_purchase_succeeded", "assigned", "released", "unavailable", "activation_failed", "manual_review", "canceled" ] }, "providerOwnershipClaimed": { "type": "boolean", "const": false }, "ttlExpiresAt": { "type": "string", "format": "date-time" }, "customerSafeStatus": { "type": "string", "enum": [ "reserved", "activation_pending", "assigned", "unavailable", "active", "manual_review" ] } } }, "NumberReservationResponse": { "type": "object", "additionalProperties": true, "required": [ "event", "reservation" ], "properties": { "event": { "type": "string", "enum": [ "commercial_number_reservation_created", "commercial_number_activation_completed" ] }, "reservation": { "$ref": "#/components/schemas/NumberReservation" } } }, "OnboardingMilestones": { "type": "object", "additionalProperties": true, "required": [ "contractVersion", "current", "history" ], "properties": { "contractVersion": { "type": "string", "const": "onboarding-milestones.v1" }, "available": { "type": "boolean", "description": "False when the durable capability is unavailable; no completion is inferred." }, "current": { "oneOf": [ { "$ref": "#/components/schemas/OnboardingMilestoneObservation" }, { "type": "null" } ] }, "history": { "type": "array", "maxItems": 25, "description": "Latest observations first, including the current entry. These are observations since installation, not historical first-ever claims.", "items": { "$ref": "#/components/schemas/OnboardingMilestoneObservation" } }, "freshness": { "type": "object", "additionalProperties": true, "description": "Native116 reads persisted observations. Native117 evaluates live canonical facts without writing historical observations; refresh persists a changed source projection.", "properties": { "mode": { "type": "string", "enum": [ "persisted", "live-canonical" ] }, "refreshRequired": { "type": "boolean" }, "stale": { "type": "boolean" }, "currentSourceDigest": { "type": [ "string", "null" ] }, "persistedSourceDigest": { "type": [ "string", "null" ] } } }, "currentState": { "$ref": "#/components/schemas/OnboardingMilestoneCurrentState" }, "workflow": { "$ref": "#/components/schemas/OnboardingWorkflow" }, "effectiveEntitlements": { "type": "object", "additionalProperties": true, "description": "Live server-derived effective entitlement and capability provenance. Unknown evidence is never promoted to verified.", "properties": { "contractVersion": { "type": "string", "const": "effective-entitlement.v1" }, "status": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "provenance": { "type": [ "object", "null" ] }, "capabilities": { "type": "object", "additionalProperties": true } } } } }, "OnboardingWorkflowCommand": { "type": "object", "additionalProperties": false, "required": [ "channels", "direction", "expectedVersion", "requestId" ], "properties": { "channels": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "portal", "api", "email" ] } }, "direction": { "type": "string", "enum": [ "send", "receive", "both" ] }, "expectedVersion": { "type": "integer", "minimum": 0, "maximum": 999999999 }, "requestId": { "type": "string", "format": "uuid" } } }, "CustomerReadinessExceptionCommand": { "type": "object", "additionalProperties": false, "required": [ "action", "gate", "dependencyDigest", "expectedVersion", "requestId", "reasonCode", "expiresAt" ], "properties": { "action": { "type": "string", "enum": [ "send", "receive", "numberAcquisition" ] }, "gate": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9-]{0,63}$" }, "dependencyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expectedVersion": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "requestId": { "type": "string", "format": "uuid" }, "reasonCode": { "type": "string", "enum": [ "awaiting-customer", "awaiting-provider", "investigating", "scheduled-review" ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "description": "Exact UTC timestamp; a new annotation must expire within 24 hours. An exact expired replay remains readable as expired." } } }, "CustomerReadinessException": { "type": "object", "required": [ "id", "action", "gate", "dependencyDigest", "version", "reasonCode", "expiresAt", "createdAt", "role", "actorDigest", "status", "annotationOnly", "grantsAccess", "authorizationReference" ], "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "send", "receive", "numberAcquisition" ] }, "gate": { "type": "string" }, "dependencyDigest": { "type": "string" }, "version": { "type": "integer" }, "reasonCode": { "type": "string", "enum": [ "awaiting-customer", "awaiting-provider", "investigating", "scheduled-review" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "role": { "type": "string", "enum": [ "owner", "admin" ] }, "actorDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "type": "string", "enum": [ "active", "expired", "source-changed" ] }, "annotationOnly": { "type": "boolean", "const": true }, "grantsAccess": { "type": "boolean", "const": false }, "authorizationReference": { "type": "string", "const": "customer-readiness-annotation.v1/owner-admin" } } }, "CustomerReadinessPolicyCommand": { "type": "object", "additionalProperties": false, "required": [ "operatingPolicy", "expectedVersion", "requestId" ], "properties": { "operatingPolicy": { "type": "string", "enum": [ "non-phi-only", "regulated" ] }, "expectedVersion": { "type": "integer", "minimum": 0, "maximum": 999999999 }, "requestId": { "type": "string", "format": "uuid" } } }, "CustomerReadinessPolicy": { "type": "object", "required": [ "version", "selection", "editable" ], "properties": { "version": { "type": "integer", "minimum": 0 }, "selection": { "type": "string", "enum": [ "unknown", "non-phi-only", "regulated" ] }, "editable": { "type": "boolean" }, "selectedAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "object", "additionalProperties": true } } }, "CustomerReadinessGate": { "type": "object", "required": [ "key", "status", "source", "effectiveVersion", "scope", "observedAt", "expiresAt", "blocker", "owner", "recheck" ], "properties": { "key": { "type": "string" }, "status": { "type": "string", "enum": [ "eligible", "verified", "pending", "blocked", "unknown", "not-applicable" ] }, "source": { "type": "object", "additionalProperties": true }, "effectiveVersion": { "type": "string" }, "scope": { "type": "object", "additionalProperties": true }, "observedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "blocker": { "type": [ "object", "null" ], "additionalProperties": true }, "owner": { "type": "string", "enum": [ "customer-owner", "support", "platform-operations" ] }, "recheck": { "type": "object", "additionalProperties": true } } }, "CustomerReadiness": { "type": "object", "required": [ "contractVersion", "sourceVersion", "nativeOrdinal", "accountId", "tenantId", "environmentScope", "runtimeEnvironment", "applicability", "operatingPolicy", "phiPermitted", "workflow", "initialEligibility", "verifiedActivation", "gates" ], "properties": { "contractVersion": { "type": "string", "const": "customer-readiness.v1" }, "sourceVersion": { "type": "string", "const": "native118" }, "nativeOrdinal": { "type": "integer", "const": 118 }, "accountId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "environmentScope": { "type": "string" }, "runtimeEnvironment": { "type": "string" }, "editable": { "type": "boolean", "description": "Current interactive owner or administrator may request a durable readiness recheck." }, "applicability": { "type": "string", "enum": [ "enrolled", "migration-required" ] }, "phiPermitted": { "type": "boolean", "const": false }, "operatingPolicy": { "$ref": "#/components/schemas/CustomerReadinessPolicy" }, "workflow": { "type": "object", "additionalProperties": true }, "initialEligibility": { "type": "object", "required": [ "send", "receive", "numberAcquisition" ], "properties": { "send": { "$ref": "#/components/schemas/CustomerReadinessGate" }, "receive": { "$ref": "#/components/schemas/CustomerReadinessGate" }, "numberAcquisition": { "$ref": "#/components/schemas/CustomerReadinessGate" } } }, "verifiedActivation": { "type": "object", "required": [ "send", "receive" ], "properties": { "send": { "$ref": "#/components/schemas/CustomerReadinessGate" }, "receive": { "$ref": "#/components/schemas/CustomerReadinessGate" } } }, "gates": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReadinessGate" } }, "current": { "type": [ "object", "null" ], "additionalProperties": true }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerReadinessException" } }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "CustomerReadinessResponse": { "type": "object", "required": [ "event", "accountId", "tenantId", "readiness" ], "properties": { "event": { "type": "string", "enum": [ "customer_readiness", "customer_readiness_rechecked", "customer_readiness_policy_updated", "customer_readiness_exception_recorded" ] }, "accountId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "readiness": { "$ref": "#/components/schemas/CustomerReadiness" } } }, "OnboardingWorkflow": { "type": "object", "additionalProperties": true, "properties": { "version": { "type": "integer", "minimum": 0 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "portal", "api", "email" ] } }, "direction": { "type": "string", "enum": [ "send", "receive", "both", "unknown" ] }, "qualificationEpoch": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "epochStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "editable": { "type": "boolean", "description": "True only when the current interactive account owner or administrator may update this workflow. The command rechecks authority." } } }, "OnboardingMilestoneCurrentState": { "type": "object", "additionalProperties": true, "required": [ "observedAt", "sourceDigest", "milestones" ], "description": "Live canonical evaluation. This is not a persisted observation and has no invented historical observation identifier.", "properties": { "observedAt": { "type": "string", "format": "date-time" }, "sourceDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "milestones": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "status", "required", "skippable", "reason", "nextAction", "sourceOccurredAt", "sourceDigest", "effectiveVersion", "expiresAt" ], "properties": { "key": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "eligible", "in-progress", "verified", "blocked", "unknown", "not-applicable" ] }, "required": { "type": "boolean" }, "skippable": { "type": "boolean" }, "reason": { "type": "string" }, "nextAction": { "type": "string" }, "sourceOccurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "sourceDigest": { "type": [ "string", "null" ] }, "effectiveVersion": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "OnboardingMilestoneObservation": { "type": "object", "additionalProperties": true, "required": [ "observationId", "observedAt", "sourceDigest", "milestones" ], "properties": { "observationId": { "type": "string", "format": "uuid" }, "observedAt": { "type": "string", "format": "date-time", "description": "Time the system persisted this changed source projection, distinct from source occurrence times." }, "sourceDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "selectedPackageKey": { "type": [ "string", "null" ] }, "effectivePackageKey": { "type": [ "string", "null" ] }, "currentAvailability": { "type": "string", "const": "unknown", "description": "At-import publication verification does not attest current object availability." }, "milestones": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "status", "sourceOccurredAt", "source", "reason", "nextAction" ], "properties": { "key": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "eligible", "in-progress", "verified", "blocked", "unknown", "not-applicable" ] }, "required": { "type": "boolean" }, "skippable": { "type": "boolean" }, "effectiveVersion": { "type": [ "string", "null" ] }, "sourceDigest": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "sourceOccurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Metadata-only authoritative source identifiers and digests; no document payload or customer contact details." }, "reason": { "type": "string" }, "nextAction": { "type": "string" } } } } } }, "NumberFulfillment": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "observedAt", "items" ], "properties": { "observedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Coherent database observation time when supplied by the native fulfillment reader." }, "schemaVersion": { "type": "string", "const": "number-fulfillment.v1" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFulfillmentItem" } } }, "description": "Projection of account-owned current records. Null means evidence unavailable. Configured capabilities and assigned status do not verify sending or receiving. Current state does not provide historical milestone timestamps." }, "NumberFulfillmentMilestone": { "type": "object", "additionalProperties": false, "required": [ "confirmed", "occurredAt" ], "properties": { "confirmed": { "type": [ "boolean", "null" ], "enum": [ true, null ] }, "occurredAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "NumberFulfillmentItem": { "type": "object", "additionalProperties": false, "required": [ "kind", "numberE164", "reservationId", "assignmentId", "portRequestId", "requestId", "providerDomain", "providerOrderRef", "providerCommandId", "packageCode", "capabilities", "commercialTerms", "createdAt", "updatedAt", "state", "progress", "nextAction", "evidenceGaps", "providerCommandStatus", "providerRequestId", "providerResourceRef", "providerReadback", "routing", "billing", "providerCommandResourceRef" ], "properties": { "kind": { "type": "string", "enum": [ "purchase", "assignment", "port" ] }, "numberE164": { "type": [ "string", "null" ] }, "reservationId": { "type": [ "string", "null" ] }, "assignmentId": { "type": [ "string", "null" ] }, "portRequestId": { "type": [ "string", "null" ] }, "requestId": { "type": [ "string", "null" ] }, "providerDomain": { "type": [ "string", "null" ] }, "providerOrderRef": { "type": [ "string", "null" ] }, "providerCommandId": { "type": [ "string", "null" ] }, "packageCode": { "type": [ "string", "null" ] }, "capabilities": { "type": "object", "additionalProperties": false, "required": [ "fax", "voice" ], "properties": { "fax": { "type": [ "boolean", "null" ] }, "voice": { "type": [ "boolean", "null" ] } } }, "commercialTerms": { "type": "object", "additionalProperties": false, "required": [ "billingClass", "extraNumberMonthlyAmountCents", "currencyCode" ], "properties": { "billingClass": { "type": [ "string", "null" ], "enum": [ "included", "extra", null ] }, "extraNumberMonthlyAmountCents": { "type": [ "integer", "null" ], "minimum": 0 }, "currencyCode": { "type": [ "string", "null" ] } } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "type": "string", "enum": [ "requested", "reserved", "purchase_submitted", "port_submitted", "provider_pending", "fulfilled", "assigned", "routed", "verified", "rejected", "ambiguous", "canceled" ] }, "progress": { "type": "object", "additionalProperties": false, "required": [ "requested", "reserved", "purchase_submitted", "port_submitted", "provider_pending", "fulfilled", "assigned", "routed", "verified", "rejected", "ambiguous", "canceled" ], "properties": { "requested": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "reserved": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "purchase_submitted": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "port_submitted": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "provider_pending": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "fulfilled": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "assigned": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "routed": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "verified": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "rejected": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "ambiguous": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" }, "canceled": { "$ref": "#/components/schemas/NumberFulfillmentMilestone" } } }, "nextAction": { "type": "string" }, "evidenceGaps": { "type": "array", "items": { "type": "string" } }, "providerCommandStatus": { "type": [ "string", "null" ] }, "providerRequestId": { "type": [ "string", "null" ] }, "providerResourceRef": { "type": [ "string", "null" ] }, "providerReadback": { "type": "object", "additionalProperties": false, "required": [ "readbackId", "status", "observedAt" ], "properties": { "readbackId": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "observedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "routing": { "type": "object", "additionalProperties": false, "required": [ "didId", "routeId", "configured", "updatedAt" ], "properties": { "didId": { "type": [ "string", "null" ] }, "routeId": { "type": [ "string", "null" ] }, "configured": { "type": [ "boolean", "null" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "billing": { "type": "object", "additionalProperties": false, "required": [ "subscriptionId", "subscriptionStatus", "billingAccountId" ], "properties": { "subscriptionId": { "type": [ "string", "null" ] }, "subscriptionStatus": { "type": [ "string", "null" ] }, "billingAccountId": { "type": [ "string", "null" ] } } }, "providerCommandResourceRef": { "type": [ "string", "null" ] } } }, "NumberStatusResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "tenantId", "accountId", "assignments", "reservations", "manualReview" ], "properties": { "fulfillment": { "$ref": "#/components/schemas/NumberFulfillment" }, "event": { "type": "string", "enum": [ "commercial_number_status" ] }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "assignments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "reservations": { "type": "array", "items": { "$ref": "#/components/schemas/NumberReservation" } }, "manualReview": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "PortRequestCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "numbers", "losingCarrierName", "losingCarrierAccountRef", "serviceAddressSummary", "authorizedSignerName", "loaDocumentId" ], "properties": { "numbers": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, "losingCarrierName": { "type": "string", "maxLength": 128 }, "losingCarrierAccountRef": { "type": "string", "maxLength": 128 }, "serviceAddressSummary": { "type": "object", "additionalProperties": true, "description": "Structured service-address summary; do not include raw document payloads." }, "authorizedSignerName": { "type": "string", "maxLength": 128 }, "loaDocumentId": { "type": "string", "format": "uuid" }, "supportingDocumentIds": { "type": "array", "maxItems": 20, "items": { "type": "string", "format": "uuid" } } } }, "PortLoaTemplateResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "fileName", "contentType", "pdfBase64", "sizeBytes" ], "properties": { "event": { "type": "string", "enum": [ "commercial_port_loa_template" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string", "enum": [ "application/pdf" ] }, "pdfBase64": { "type": "string", "contentEncoding": "base64" }, "sizeBytes": { "type": "integer", "minimum": 1 } } }, "PortLoaDocumentCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "numbers", "losingCarrierName", "losingCarrierAccountRef", "authorizedSignerName" ], "properties": { "numbers": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string" } }, "losingCarrierName": { "type": "string", "maxLength": 160 }, "losingCarrierAccountRef": { "type": "string", "maxLength": 160 }, "accountHolderName": { "type": "string", "maxLength": 180 }, "authorizedSignerName": { "type": "string", "maxLength": 160 }, "authorizedSignerTitle": { "type": "string", "maxLength": 160 }, "serviceAddressSummary": { "type": "object", "additionalProperties": true }, "signatureText": { "type": "string", "maxLength": 160 }, "signatureImageDataUrl": { "type": "string", "maxLength": 750000 } } }, "PortLoaDocumentResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "document" ], "properties": { "event": { "type": "string", "enum": [ "commercial_port_loa_document_created" ] }, "document": { "$ref": "#/components/schemas/Document" } } }, "PortRequest": { "type": "object", "additionalProperties": false, "required": [ "portRequestId", "tenantId", "accountId", "portRequestStatus", "numbers", "customerSafeStatus", "nextAction", "providerSubmitted", "loaRequired", "loaDocumentId", "supportingDocumentIds" ], "properties": { "portRequestId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "portRequestStatus": { "type": "string", "description": "Current recorded status. Unknown values are retained and projected as ambiguous fulfillment for safe follow-up." }, "numbers": { "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, "customerSafeStatus": { "type": "string", "enum": [ "port_review", "activation_pending", "action_needed", "active", "manual_review", "changes_requested", "approval_required", "submission_pending", "port_submitted", "port_scheduled", "port_completed", "port_canceled", "rejected" ] }, "nextAction": { "type": "string" }, "providerSubmitted": { "type": "boolean", "description": "Whether the owned request records a provider port reference. This alone does not prove transfer completion." }, "loaRequired": { "type": "boolean", "const": true }, "loaDocumentId": { "type": "string", "format": "uuid", "nullable": true }, "requestId": { "type": [ "string", "null" ] }, "loaValidation": { "type": [ "object", "null" ], "additionalProperties": true }, "supportingDocumentIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "PortRequestResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "portRequest" ], "properties": { "event": { "type": "string", "enum": [ "commercial_port_request_created" ] }, "portRequest": { "$ref": "#/components/schemas/PortRequest" } } }, "PortRequestListResponse": { "type": "object", "additionalProperties": false, "required": [ "event", "tenantId", "accountId", "items" ], "properties": { "fulfillment": { "$ref": "#/components/schemas/NumberFulfillment" }, "event": { "type": "string", "enum": [ "commercial_port_request_list" ] }, "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PortRequest" } } } }, "DecorationBand": { "type": "object", "additionalProperties": false, "required": [ "enabled", "template", "alignment" ], "properties": { "enabled": { "type": "boolean" }, "template": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "Required when enabled and null when disabled. At most 256 Unicode code points, one or two explicit lines, and only the seven exact fax-decoration-template.v1 double-brace fields." }, "alignment": { "type": "string", "enum": [ "left", "center", "right" ] } }, "allOf": [ { "if": { "properties": { "enabled": { "const": true } } }, "then": { "properties": { "template": { "type": "string" } }, "required": [ "template" ] } }, { "if": { "properties": { "enabled": { "const": false } } }, "then": { "properties": { "template": { "type": "null" } } } } ] }, "DecorationPolicyUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "header", "footer" ], "properties": { "header": { "$ref": "#/components/schemas/DecorationBand" }, "footer": { "$ref": "#/components/schemas/DecorationBand" } } }, "SharedDecorationEnablementRequest": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "description": "Customers can set only this Boolean. Managed template, alignment, style, font, layout, and version input is rejected." }, "DecorationConfigurationResponse": { "type": "object", "additionalProperties": false, "required": [ "version", "sourceKind", "state", "managed", "globallyAvailable", "accountEnabled", "header", "footer", "templateGrammarVersion", "layoutVersion", "fontId" ], "properties": { "version": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "sourceKind": { "type": "string", "enum": [ "assigned_did", "shared_sender" ] }, "state": { "type": "string", "enum": [ "enabled", "disabled", "unavailable" ] }, "managed": { "type": "boolean" }, "globallyAvailable": { "type": [ "boolean", "null" ] }, "accountEnabled": { "type": [ "boolean", "null" ] }, "header": { "$ref": "#/components/schemas/DecorationBand" }, "footer": { "$ref": "#/components/schemas/DecorationBand" }, "templateGrammarVersion": { "type": "string", "const": "fax-decoration-template.v1" }, "layoutVersion": { "type": "string", "const": "fax-decoration-layout.v1" }, "fontId": { "type": "string", "const": "fax-decoration-font.noto-sans-regular.v1" } } }, "DecorationPreviewAssignedRequest": { "type": "object", "additionalProperties": false, "required": [ "sourceKind", "didId", "draft" ], "properties": { "sourceKind": { "type": "string", "const": "assigned_did" }, "didId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "draft": { "$ref": "#/components/schemas/DecorationPolicyUpdateRequest" } } }, "DecorationPreviewManagedRequest": { "type": "object", "additionalProperties": false, "required": [ "sourceKind", "didId" ], "properties": { "sourceKind": { "type": "string", "const": "shared_sender" }, "didId": { "$ref": "#/components/schemas/DurableOpaquePublicId" } } }, "DecorationPreviewCreateRequest": { "oneOf": [ { "$ref": "#/components/schemas/DecorationPreviewAssignedRequest" }, { "$ref": "#/components/schemas/DecorationPreviewManagedRequest" } ] }, "DecorationPreviewArtifact": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "state", "contentType", "sizeBytes", "availableUntil" ], "properties": { "artifactId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "state": { "type": "string", "enum": [ "available", "expired", "unavailable" ] }, "contentType": { "type": "string", "const": "application/pdf" }, "sizeBytes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 104857600 }, "availableUntil": { "type": "string", "format": "date-time" } } }, "DecorationPreviewOperationResponse": { "type": "object", "additionalProperties": false, "required": [ "operationId", "type", "state", "resultCode", "failureCode", "createdAt", "completedAt", "artifact" ], "properties": { "operationId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "type": { "type": "string", "const": "decoration_preview" }, "state": { "type": "string", "enum": [ "accepted", "confirmed", "running", "succeeded", "failed", "reconciliation_required", "existing" ] }, "resultCode": { "type": [ "string", "null" ], "maxLength": 64 }, "failureCode": { "type": [ "string", "null" ], "maxLength": 64 }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "artifact": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecorationPreviewArtifact" } ] } } }, "DecorationPreviewArtifactAccessResponse": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "accessUrl", "expiresAt" ], "properties": { "artifactId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "accessUrl": { "type": "string", "format": "uri", "maxLength": 4096, "description": "Short-lived private artifact URL. It must not be logged or persisted by clients." }, "expiresAt": { "type": "string", "format": "date-time" } } }, "ReadyResponse": { "type": "object", "description": "Coarse public readiness and developer affordances. Dependency diagnostics are available only through authorized operator system health.", "required": [ "status", "service", "environment", "requestId" ], "properties": { "status": { "type": "string", "enum": [ "ready", "not_ready" ] }, "service": { "type": "string" }, "environment": { "type": "string" }, "requestId": { "type": "string" }, "developerCapabilities": { "description": "Versioned developer UI affordances; protected requests remain authorized by the backend.", "$ref": "#/components/schemas/DeveloperReadinessCapabilities" } } }, "DeveloperReadinessCapabilities": { "type": "object", "description": "Public UI affordances from composed runtime owners and dependency integrity. Protected operations still enforce current tenant authorization and native policy in their transactions. Clients deny absent or unknown contract versions.", "required": [ "schemaVersion", "features" ], "properties": { "schemaVersion": { "type": "string", "const": "faximus.developer-capabilities.v1" }, "features": { "type": "object", "required": [ "liveManagement", "testManagement", "legacyLiveRows" ], "properties": { "liveManagement": { "type": "boolean", "description": "Basic live API key and webhook endpoint management is available." }, "testManagement": { "type": "boolean", "description": "Composed native test runtime and mode-aware basic management owners are available." }, "legacyLiveRows": { "type": "boolean", "description": "Missing or null row businessMode may be projected as live only. Explicit modes must match the selected mode." } } } } }, "DurableOperationSummary": { "type": "object", "additionalProperties": false, "required": [ "operationId", "operationType", "state", "createdAt", "updatedAt" ], "properties": { "operationId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "operationType": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$", "minLength": 3, "maxLength": 64 }, "state": { "type": "string", "enum": [ "accepted", "pending_confirmation", "queued", "processing", "completed", "completed_with_errors", "failed", "canceled", "expired", "reconciliation_required" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "DurableFaxBatchItemSummary": { "type": "object", "additionalProperties": false, "required": [ "itemId", "ordinal", "resultState" ], "properties": { "itemId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 99 }, "resultState": { "type": "string", "enum": [ "reserved", "created", "skipped", "failed" ] }, "faxJobId": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DurableOpaquePublicId" } ] }, "resultCode": { "type": [ "null", "string" ], "maxLength": 64 } } }, "DurableFaxBatchSummary": { "type": "object", "additionalProperties": false, "required": [ "batchId", "kind", "state", "requestedCount", "createdCount", "skippedCount", "failedCount", "createdAt", "updatedAt" ], "properties": { "batchId": { "$ref": "#/components/schemas/DurableOpaquePublicId" }, "kind": { "type": "string", "enum": [ "multi_send", "bulk_resend" ] }, "state": { "type": "string", "enum": [ "accepted", "processing", "completed", "completed_with_errors", "failed" ] }, "requestedCount": { "type": "integer", "minimum": 1, "maximum": 100 }, "createdCount": { "type": "integer", "minimum": 0, "maximum": 100 }, "skippedCount": { "type": "integer", "minimum": 0, "maximum": 100 }, "failedCount": { "type": "integer", "minimum": 0, "maximum": 100 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "DurableOpaquePublicId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Opaque public identifier. It does not reveal an internal database row identity." }, "WebhookEventType": { "type": "string", "enum": [ "fax.delivery.confirmed", "fax.delivery.failed", "fax.delivery.unconfirmed", "fax.delivery.evidence_incomplete", "fax.delivery.not_attempted" ] }, "NativeTestCreateDocumentRequest": { "type": "object", "additionalProperties": false, "required": [ "fixture" ], "properties": { "fixture": { "type": "string", "enum": [ "one-page", "two-pages" ] } } }, "NativeTestCreateFaxJobRequest": { "type": "object", "additionalProperties": false, "required": [ "documentId", "scenario" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "scenario": { "type": "string", "enum": [ "success", "busy", "no-answer", "invalid-document", "transient-retry-success", "exhausted-permanent-failure", "partial-unconfirmed", "cancellation" ] } } }, "NativeTestDocumentResponse": { "type": "object", "required": [ "documentId", "state", "fixture", "synthetic", "businessMode" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "created", "ready" ] }, "fixture": { "type": "string", "enum": [ "one-page", "two-pages" ] }, "synthetic": { "type": "boolean", "const": true }, "businessMode": { "type": "string", "const": "test" } } }, "NativeTestFaxJobResponse": { "type": "object", "required": [ "faxJobId", "state", "scenario", "ordinal", "synthetic", "businessMode", "catalogVersion", "carrierDeliveryProven" ], "properties": { "faxJobId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "description": "Simulator state. Unknown future values remain unknown; never infer carrier delivery.", "examples": [ "accepted", "processing", "retrying", "succeeded", "failed", "partial_unconfirmed", "canceled", "blocked" ] }, "scenario": { "type": "string", "enum": [ "success", "busy", "no-answer", "invalid-document", "transient-retry-success", "exhausted-permanent-failure", "partial-unconfirmed", "cancellation" ] }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 3 }, "synthetic": { "type": "boolean", "const": true }, "businessMode": { "type": "string", "const": "test" }, "catalogVersion": { "type": "string", "const": "developer-test-scenarios.v2" }, "carrierDeliveryProven": { "type": "boolean", "const": false }, "failureCode": { "type": [ "string", "null" ] }, "simulationOutcome": { "type": "string" }, "deliveryStatus": { "type": "string", "const": "synthetic" }, "deliveryConfidence": { "type": [ "number", "null" ], "const": null, "description": "Synthetic scenarios provide no carrier delivery confidence." } } }, "WebhookControlsReadiness": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "backendReady", "accountId", "endpointId", "businessMode", "role", "actions", "currentSecretVersionId" ], "properties": { "schemaVersion": { "const": "faximus.webhook-controls-readiness.v1" }, "backendReady": { "const": true }, "accountId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "businessMode": { "enum": [ "live", "test" ] }, "role": { "enum": [ "owner", "admin" ] }, "actions": { "type": "array", "uniqueItems": true, "items": { "enum": [ "history", "rotate", "revoke", "replay", "test" ] } }, "currentSecretVersionId": { "type": [ "string", "null" ], "format": "uuid" } } }, "WebhookSigningState": { "type": "object", "required": [ "tenantId", "accountId", "endpointId", "businessMode", "contextCleared", "currentVersionId", "emergencyRevoked", "urlRevision" ], "properties": { "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "businessMode": { "enum": [ "live", "test" ] }, "contextCleared": { "const": true }, "currentVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "previousVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "previousValidUntil": { "type": [ "string", "null" ], "format": "date-time" }, "emergencyRevoked": { "type": "boolean" }, "urlRevision": { "type": "integer" }, "readiness": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "backendReady", "accountId", "endpointId", "businessMode", "role", "actions", "currentSecretVersionId" ], "properties": { "schemaVersion": { "const": "faximus.webhook-controls-readiness.v1" }, "backendReady": { "const": true }, "accountId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "businessMode": { "enum": [ "live", "test" ] }, "role": { "enum": [ "owner", "admin" ] }, "actions": { "type": "array", "uniqueItems": true, "items": { "enum": [ "history", "rotate", "revoke", "replay", "test" ] } }, "currentSecretVersionId": { "type": [ "string", "null" ], "format": "uuid" } } } } }, "WebhookRotationRequest": { "type": "object", "additionalProperties": false, "required": [ "operationId", "expectedVersion" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": [ "string", "null" ], "format": "uuid" }, "overlapSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 3600 } } }, "WebhookRevocationRequest": { "type": "object", "additionalProperties": false, "required": [ "operationId", "expectedVersion" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": [ "string", "null" ], "format": "uuid" } } }, "WebhookReplayRequest": { "type": "object", "additionalProperties": false, "required": [ "operationId", "originalDeliveryId" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "originalDeliveryId": { "type": "string", "format": "uuid" } } }, "SyntheticWebhookTestRequest": { "type": "object", "additionalProperties": false, "required": [ "jobId", "operationId" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } }, "SyntheticWebhookTestResponse": { "type": "object", "required": [ "tenantId", "accountId", "endpointId", "businessMode", "contextCleared", "value" ], "properties": { "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "businessMode": { "enum": [ "live", "test" ] }, "contextCleared": { "const": true }, "value": { "type": "object", "additionalProperties": false, "required": [ "eventId", "deliveryId", "jobId", "operationId", "alreadyApplied" ], "properties": { "eventId": { "type": "string", "format": "uuid" }, "deliveryId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" }, "alreadyApplied": { "type": "boolean" } } } } }, "WebhookReplayResponse": { "type": "object", "required": [ "tenantId", "accountId", "endpointId", "businessMode", "contextCleared", "value" ], "properties": { "tenantId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "businessMode": { "enum": [ "live", "test" ] }, "contextCleared": { "const": true }, "value": { "type": "object", "additionalProperties": false, "required": [ "deliveryId", "eventId", "alreadyApplied" ], "properties": { "deliveryId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "alreadyApplied": { "type": "boolean" } } } } }, "WebhookHistoryPage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/WebhookHistoryDelivery" } }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512 } } }, "NativeDocumentOperationRequest": { "oneOf": [ { "$ref": "#/components/schemas/CreateDocumentRequest" }, { "$ref": "#/components/schemas/NativeTestCreateDocumentRequest" } ] }, "NativeFaxJobOperationRequest": { "oneOf": [ { "$ref": "#/components/schemas/CreateFaxJobRequest" }, { "$ref": "#/components/schemas/NativeTestCreateFaxJobRequest" } ] }, "WebhookSigningOperationResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookSigningState" }, { "type": "object", "required": [ "operationId", "alreadyApplied", "firstApplied" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "versionId": { "type": [ "string", "null" ], "format": "uuid" }, "alreadyApplied": { "type": "boolean" }, "firstApplied": { "type": "boolean" }, "signingSecret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$", "writeOnly": false, "description": "Returned only when this rotate operation first applies. Copy once; state reads and reconciliation never reveal it." } } } ] }, "WebhookHistoryAttempt": { "type": "object", "additionalProperties": false, "required": [ "attemptId", "attemptedAt", "result", "httpStatus", "errorCode", "durationMs", "signingVersionId", "retryAfterSeconds" ], "properties": { "attemptId": { "type": "string", "format": "uuid" }, "attemptedAt": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "httpStatus": { "type": [ "integer", "null" ] }, "errorCode": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "signingVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "retryAfterSeconds": { "type": [ "integer", "null" ] } } }, "WebhookHistoryDelivery": { "type": "object", "additionalProperties": false, "required": [ "deliveryId", "eventId", "endpointId", "businessMode", "eventType", "eventSchemaVersion", "createdAt", "updatedAt", "deliveredAt", "failedAt", "status", "attemptCount", "nextRetryAt", "exhausted", "replayOperationId", "httpStatus", "errorCode", "signingVersionId", "replayOfDeliveryId", "attempts" ], "properties": { "deliveryId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "businessMode": { "enum": [ "live", "test" ] }, "eventType": { "type": "string" }, "eventSchemaVersion": { "type": [ "string", "null" ], "maxLength": 64 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "failedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "Unknown future statuses must remain unknown; callback delivery does not prove fax delivery." }, "attemptCount": { "type": "integer", "minimum": 0 }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "exhausted": { "type": "boolean" }, "replayOperationId": { "type": [ "string", "null" ], "format": "uuid" }, "httpStatus": { "type": [ "integer", "null" ] }, "errorCode": { "type": [ "string", "null" ] }, "signingVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "replayOfDeliveryId": { "type": [ "string", "null" ], "format": "uuid" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookHistoryAttempt" } } } } } } }