{ "openapi": "3.0.0", "info": { "title": "SmartPricingTable API", "version": "1.0.0", "description": "API documentation for SmartPricingTable application", "contact": { "name": "SmartPricingTable Support", "url": "https://smartpricingtable.com" } }, "servers": [ { "url": "http://localhost:3000", "description": "Development server" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token obtained during authentication" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API Key authentication (format: Bearer YOUR_API_KEY)" } }, "schemas": { "ProposalDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the proposal" }, "org_id": { "type": "string", "description": "Organization that owns this proposal" }, "name": { "type": "string", "description": "Proposal name/title" }, "status": { "$ref": "#/components/schemas/ProposalDisplayStatus", "description": "Current workflow status of the proposal" }, "settings": { "$ref": "#/components/schemas/ApiProposalSettings", "description": "Display and behavior settings for the proposal (API format, snake_case)" }, "design": { "$ref": "#/components/schemas/ProposalDesign", "description": "Visual design settings" }, "integrations": { "anyOf": [ { "$ref": "#/components/schemas/ProposalIntegrations" }, { "type": "null" } ], "description": "External integration data (CRM, payment, etc.)" }, "custom_variables": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalCustomVariable" }, "description": "Custom variables used in the proposal content" }, "status_detail": { "$ref": "#/components/schemas/ProposalStatusDetail", "description": "Status lifecycle and resolution details" }, "created_at": { "type": "string", "description": "When the proposal was created (ISO 8601 timestamp)" }, "updated_at": { "type": "string", "description": "When the proposal was last updated (ISO 8601 timestamp)" }, "archived": { "type": "boolean", "description": "Whether the proposal is archived" }, "archived_at": { "type": [ "string", "null" ], "description": "When the proposal was archived (ISO 8601 timestamp), or null if not archived" }, "is_template": { "type": "boolean", "description": "Whether this proposal is a reusable template" }, "is_starred": { "type": "boolean", "description": "Whether the current user has starred this proposal" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags assigned to this proposal" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/ProposalUser" }, { "type": "null" } ], "description": "User who created the proposal" }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/ProposalUser" }, { "type": "null" } ], "description": "User who last updated the proposal" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalPage" }, "description": "Ordered list of proposal pages" }, "cached_totals": { "anyOf": [ { "$ref": "#/components/schemas/ProposalCachedTotals" }, { "type": "null" } ], "description": "Cached pricing totals for quick display" }, "timestamps": { "type": "object", "properties": { "sent": { "type": "string" }, "won": { "type": "string" }, "lost": { "type": "string" }, "firstViewed": { "type": "string" }, "lastViewed": { "type": "string" }, "openedNotifications": { "$ref": "#/components/schemas/Record%3Cstring%2Cstring%3E" } }, "additionalProperties": false, "description": "Key lifecycle timestamps" }, "is_library": { "type": "boolean", "description": "Whether this proposal is a library item" }, "v1_signing": { "$ref": "#/components/schemas/V1SigningData", "description": "V1 legacy signing data (Xodo Sign), present only for imported pending proposals" } }, "required": [ "id", "org_id", "name", "status", "creator", "pages" ], "additionalProperties": false, "description": "Complete proposal with all details, pages, items, and metadata" }, "UpdateProposalApiInput": { "type": "object", "additionalProperties": false, "properties": { "integrations": { "anyOf": [ { "$ref": "#/components/schemas/ProposalIntegrationsInput" }, { "type": "null" } ], "description": "External integrations (write model — payment has settings only, no transactions)" }, "timestamps": { "type": "object", "properties": { "sent": { "type": "string" }, "won": { "type": "string" }, "lost": { "type": "string" }, "firstViewed": { "type": "string" }, "lastViewed": { "type": "string" }, "openedNotifications": { "$ref": "#/components/schemas/Record%3Cstring%2Cstring%3E" } }, "additionalProperties": false, "description": "Key lifecycle timestamps" }, "name": { "type": "string", "description": "Proposal name/title" }, "status": { "$ref": "#/components/schemas/ProposalDisplayStatus", "description": "Current workflow status of the proposal" }, "settings": { "$ref": "#/components/schemas/ApiProposalSettings", "description": "Display and behavior settings for the proposal (API format, snake_case)" }, "design": { "$ref": "#/components/schemas/ProposalDesign", "description": "Visual design settings for the proposal" }, "custom_variables": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalCustomVariable" }, "description": "Custom variables used in the proposal content" }, "status_detail": { "$ref": "#/components/schemas/ProposalStatusDetail", "description": "Status lifecycle and resolution details" }, "is_template": { "type": "boolean", "description": "Whether this proposal is a reusable template" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags assigned to this proposal" } }, "description": "Input for updating an existing proposal. Only include the fields you want to change." }, "ProposalListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the proposal" }, "status": { "$ref": "#/components/schemas/ProposalDisplayStatus", "description": "Current workflow status of the proposal" }, "name": { "type": "string", "description": "Display name of the proposal" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/ProposalUser" }, { "type": "null" } ], "description": "User who created the proposal" }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/ProposalUser" }, { "type": "null" } ], "description": "User who last updated the proposal" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the proposal was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp when the proposal was last updated" }, "archived": { "type": "boolean", "description": "Whether the proposal is archived" }, "archived_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the proposal was archived, or null if not archived" }, "settings": { "$ref": "#/components/schemas/ApiProposalSettings", "description": "Display and behavior settings for the proposal (API format, snake_case)" }, "is_template": { "type": "boolean", "description": "Whether this proposal is a reusable template" }, "is_starred": { "type": "boolean", "description": "Whether the current user has starred this proposal" }, "cached_totals": { "anyOf": [ { "$ref": "#/components/schemas/ProposalCachedTotals" }, { "type": "null" } ], "description": "Cached pricing totals for quick display" }, "status_detail": { "$ref": "#/components/schemas/ProposalListItemStatusDetail", "description": "Status lifecycle details (subset relevant to list views)" }, "crm_linked": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "recipient_name": { "type": "string" } }, "required": [ "provider" ], "additionalProperties": false }, { "type": "null" } ], "description": "CRM link info when proposal is linked to a CRM contact/deal" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags assigned to this proposal" } }, "required": [ "id", "status", "name", "created_by", "updated_by", "created_at", "updated_at" ], "additionalProperties": false, "description": "Summary of a proposal for use in list views" }, "Pagination": { "type": "object", "description": "Pagination metadata for list endpoints", "properties": { "page": { "type": "integer", "description": "Current page number", "example": 1 }, "limit": { "type": "integer", "description": "Items per page", "example": 20 }, "total": { "type": "integer", "description": "Total number of items", "example": 150 }, "pages": { "type": "integer", "description": "Total number of pages", "example": 8 } } }, "CreateProposalApiInput": { "type": "object", "additionalProperties": false, "properties": { "templateId": { "type": "string", "description": "Template ID to duplicate from" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalPageCreateInput" }, "description": "Pages array (for duplication, empty array prevents default page creation)" }, "integrations": { "anyOf": [ { "$ref": "#/components/schemas/ProposalIntegrationsInput" }, { "type": "null" } ], "description": "External integrations (write model — payment has settings only, no transactions)" }, "settings": { "$ref": "#/components/schemas/ApiProposalSettings", "description": "Display and behavior settings for the proposal (API format, snake_case)" }, "design": { "$ref": "#/components/schemas/ProposalDesign", "description": "Visual design settings for the proposal" }, "custom_variables": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalCustomVariable" }, "description": "Custom variables used in the proposal content" }, "is_template": { "type": "boolean", "description": "Whether this proposal is a reusable template" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags assigned to this proposal" }, "name": { "type": "string", "description": "Proposal name (required)" } }, "required": [ "name" ], "description": "Input for creating a new proposal." }, "CreateProposalResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the created proposal" } }, "required": [ "id" ], "additionalProperties": false, "description": "Response from creating a new proposal. Only the ID is returned;\ncallers navigate to the proposal editor which fetches the full detail." }, "ProposalPageCreateInput": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "description": "Rich text content of the page" }, "order_key": { "type": "number", "description": "Sort position of the page within the proposal" }, "kind": { "type": "string", "description": "Type of page (e.g., content, pricing, signatures)" }, "scopeId": { "type": "string", "description": "ID of the scope of work section this page belongs to" }, "isScopeOfWork": { "type": "boolean", "description": "Whether this page is a scope of work pricing page" }, "isSignaturesPage": { "type": "boolean", "description": "Whether this is the signatures page" }, "screenshotUrl": { "type": [ "string", "null" ], "description": "URL of the page screenshot thumbnail" }, "showCents": { "type": "boolean", "description": "Whether to display cents in price values" }, "salesTaxPercentage": { "type": "string", "description": "Sales tax percentage applied to this page" }, "lineItemsStartExpanded": { "type": "string", "enum": [ "none", "all", "first" ], "description": "Whether line items are expanded by default" }, "selectionType": { "type": "string", "enum": [ "single", "multiple", "loose" ], "description": "How items on this page can be selected" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags/labels applied to this page" }, "metadata": { "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E" }, "markupPercentage": { "type": "string", "description": "Markup percentage applied to items on this page" }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "fixed", "percentage" ] }, "amount": { "type": "string" }, "frequency": { "type": "string" } }, "required": [ "id", "type", "amount", "frequency" ], "additionalProperties": false }, "description": "Discount configurations for this page" }, "hideTotalsTop": { "type": "boolean", "description": "Whether to hide the totals row at the top of the page" }, "hideTotalsBottom": { "type": "boolean", "description": "Whether to hide the totals row at the bottom of the page" }, "labels": { "type": "object", "properties": { "grandTotalLabels": { "$ref": "#/components/schemas/Record%3Cstring%2Cstring%3E" }, "tax": { "type": "string" } }, "additionalProperties": false, "description": "Custom label overrides for this page" }, "displayHeading": { "type": "boolean", "description": "Whether to display the page heading" }, "hideSection": { "type": "boolean", "description": "Whether this section is hidden from view" }, "excludeFromPdf": { "type": "boolean", "description": "Whether to exclude this page from PDF exports" }, "designSettings": { "$ref": "#/components/schemas/PageDesignSettings" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/PageChild" }, "description": "Unified ordered list of groups and side-by-sides (only on scope-of-work pages)" }, "name": { "type": "string", "description": "Page name/title" } }, "required": [ "name" ], "description": "Input type for creating a new page Extends ProposalPageBase and requires proposal_id" }, "ProposalIntegrationsInput": { "type": "object", "properties": { "crm": { "anyOf": [ { "$ref": "#/components/schemas/ApiProposalCRMData" }, { "type": "null" } ], "description": "CRM integration data to link/unlink" }, "payment": { "anyOf": [ { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/PaymentSettings" } }, "required": [ "settings" ], "additionalProperties": false }, { "type": "null" } ], "description": "Payment configuration (settings only; transactions are managed server-side)" } }, "additionalProperties": false, "description": "Write-side integrations input (transactions are server-managed, not client-writable)" }, "ApiProposalSettings": { "type": "object", "properties": { "signing": { "$ref": "#/components/schemas/ApiProposalSigningSettings" }, "recipient": { "$ref": "#/components/schemas/ProposalRecipient" }, "notifications": { "$ref": "#/components/schemas/ApiProposalNotificationSettings" }, "avoid_line_item_page_breaks": { "type": "boolean" }, "hide_pdf_download": { "type": "boolean" }, "disable_proposal_access": { "type": "boolean" }, "include_modifications_in_line_item_price": { "type": "boolean" }, "hide_unselected_from_recipient": { "type": "boolean" }, "currency": { "type": "string" }, "expiring_on": { "type": [ "string", "null" ] }, "email_draft": { "type": "object", "properties": { "recipients": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ], "additionalProperties": false } } ] }, "subject": { "type": "string" }, "message": { "type": "string" }, "last_saved": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": {}, "description": "API-facing proposal settings (snake_case keys)" }, "ProposalDesign": { "type": "object", "properties": { "colors": { "type": "object", "properties": { "proposal_header": { "type": "object", "properties": { "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, "group_heading": { "type": "object", "properties": { "background": { "type": "string" }, "text": { "type": "string" }, "checkbox": { "type": "string" }, "checkmark": { "type": "string" }, "quantity": { "type": "string" }, "quantity_font": { "type": "string" } }, "additionalProperties": false }, "proposal_navigation": { "type": "object", "properties": { "background": { "type": "string" }, "link": { "type": "string" }, "selected_link": { "type": "string" }, "highlight_color": { "type": "string" }, "highlight_border": { "type": "string" } }, "additionalProperties": false }, "logo": { "type": "object", "properties": { "background": { "type": "string" }, "divider_line": { "type": "string" }, "url": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "primary_button_background": { "type": "string" }, "primary_button_color": { "type": "string" }, "primary_button_border_color": { "type": "string" }, "secondary_button_background": { "type": "string" }, "secondary_button_color": { "type": "string" }, "secondary_button_border_color": { "type": "string" }, "links": { "type": "object", "properties": { "color": { "type": "string" } }, "additionalProperties": false, "description": "Rich text / page content hyperlinks (default black)" } }, "additionalProperties": false, "description": "Color settings for proposal UI elements" }, "backgrounds": { "$ref": "#/components/schemas/ProposalDesignBackgrounds", "description": "Background image and color settings" }, "styling": { "type": "object", "properties": { "button_radius": { "type": "number" }, "group_radius": { "type": "number" }, "button_shadow": { "type": "number" }, "group_shadow": { "type": "number" }, "button_border_width": { "type": "number" }, "quantity_radius": { "type": "number" }, "page_radius": { "type": "number" } }, "additionalProperties": false, "description": "Border radius, shadow, and other styling values" }, "fonts": { "type": "object", "properties": { "default": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" }, "size": { "type": "string" } }, "additionalProperties": false }, "navigation": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" } }, "additionalProperties": false }, "heading": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" } }, "additionalProperties": false }, "group_heading": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" } }, "additionalProperties": false }, "line_item": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" } }, "additionalProperties": false }, "button": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" } }, "additionalProperties": false }, "content": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" } }, "additionalProperties": false }, "pricing": { "type": "object", "properties": { "family": { "type": "string" }, "bold": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Font family and weight settings for proposal elements" }, "logo": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] } }, "additionalProperties": false, "description": "Company logo displayed on the proposal" } }, "additionalProperties": false, "description": "Visual design settings for the proposal" }, "ProposalCustomVariable": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this custom variable" }, "type": { "type": "string", "enum": [ "single-line", "multi-line", "number", "date", "dropdown" ], "description": "Input type of the variable" }, "label": { "type": "string", "description": "Display label for the variable" }, "order": { "type": "number", "description": "Sort order position of the variable" }, "value": { "type": "string", "description": "Current value of the variable" }, "who_provides": { "type": "string", "enum": [ "we-do", "customer-does" ], "description": "Whether the variable is filled by the sender or the client" }, "source": { "type": "string", "description": "Origin source of the variable (e.g. CRM integration)" }, "required": { "type": "boolean", "description": "Whether the variable must be filled before sending" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the variable was created" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Available options for dropdown-type variables" } }, "required": [ "id", "type", "label", "order", "value" ], "additionalProperties": {}, "description": "A custom variable that can be used in proposal content" }, "ProposalDesignBackgrounds": { "type": "object", "properties": { "main": { "$ref": "#/components/schemas/ProposalDesignBackground" }, "page": { "$ref": "#/components/schemas/ProposalDesignBackground" } }, "additionalProperties": false, "description": "Background settings for proposal header and body sections" }, "ProposalDesignBackground": { "type": "object", "properties": { "image": { "type": "string", "description": "URL of the background image" }, "position": { "type": "string", "description": "CSS background-position value" }, "size": { "type": "string", "description": "CSS background-size value" }, "repeat": { "type": "string", "description": "CSS background-repeat value" }, "attachment": { "type": "string", "description": "CSS background-attachment value (e.g. \"fixed\", \"scroll\")" }, "opacity": { "type": "number", "description": "Opacity of the background image (0 to 1)" }, "colors": { "$ref": "#/components/schemas/ProposalDesignBackgroundColors", "description": "Color overrides applied with the background" } }, "additionalProperties": false, "description": "Background image settings for a proposal section" }, "ProposalDesignBackgroundColors": { "type": "object", "properties": { "background": { "type": "string", "description": "Background color override" }, "font": { "type": "string", "description": "Font color override" } }, "additionalProperties": false, "description": "Background and font color overrides" }, "ApiProposalSigningSettings": { "type": "object", "properties": { "use_accept": { "type": "boolean" }, "company_signer": { "type": "string" }, "is_contact_signer": { "type": "boolean" }, "recipient_signer": { "$ref": "#/components/schemas/ApiProposalSigner" }, "additional_signers": { "type": "array", "items": { "$ref": "#/components/schemas/ApiProposalAdditionalSigner" } }, "is_multiple_signers": { "type": "boolean" }, "custom_company_signer_name": { "type": "string" }, "custom_company_signer_email": { "type": "string" }, "override_signature_page_defaults": { "type": "boolean" }, "signature_page_agreement_text": { "type": "string" }, "signature_page_company_label": { "type": "string" }, "signature_page_client_label": { "type": "string" } }, "additionalProperties": {}, "description": "API-facing signing settings (snake_case keys)" }, "ProposalRecipient": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name of the recipient" }, "address": { "type": "string", "description": "Mailing address of the recipient company" }, "contact": { "$ref": "#/components/schemas/ProposalRecipientContact", "description": "Primary contact person at the recipient company" }, "website": { "type": "string", "description": "Website URL of the recipient company" } }, "additionalProperties": {}, "description": "The client/recipient company for a proposal" }, "ApiProposalNotificationSettings": { "type": "object", "properties": { "override_account_defaults": { "type": "boolean" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalNotificationRule" } } }, "additionalProperties": false, "description": "API-facing notification settings (snake_case keys)" }, "ProposalNotificationRule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this notification configuration" }, "event": { "$ref": "#/components/schemas/ProposalNotificationEvent", "description": "The proposal event that triggers this notification" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses to notify when the event occurs" } }, "required": [ "id", "event", "emails" ], "additionalProperties": false, "description": "Notification configuration for proposal events" }, "ProposalNotificationEvent": { "type": "string", "enum": [ "proposal_sent", "proposal_opened", "proposal_won", "proposal_lost" ], "description": "Type of notification event" }, "ProposalRecipientContact": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the contact person" }, "email": { "type": "string", "description": "Email address of the contact person" }, "phone": { "type": "string", "description": "Phone number of the contact person" } }, "additionalProperties": {}, "description": "Contact person at the recipient company" }, "ApiProposalSigner": { "type": "object", "properties": { "full_name": { "type": "string" }, "email": { "type": "string" } }, "additionalProperties": false, "description": "API-facing signer (snake_case keys)" }, "ApiProposalAdditionalSigner": { "type": "object", "properties": { "full_name": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "role": { "type": "string" } }, "description": "API-facing additional signer (snake_case keys)" }, "ApiProposalCRMData": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/CRMProvider" }, "client_id": { "type": "string", "description": "ID of the client/contact in the CRM system" }, "deal_id": { "type": "string", "description": "ID of the associated deal/opportunity in the CRM" }, "deal_url": { "type": "string", "description": "URL to view the deal in the CRM system" }, "deal_metadata": { "type": "object", "properties": { "title": { "type": "string" }, "last_synced_at": { "type": "string" }, "last_synced_price": { "type": "number" } }, "additionalProperties": false, "description": "Additional metadata from the CRM integration" } }, "required": [ "provider", "client_id" ], "additionalProperties": false, "description": "CRM integration data in API (snake_case) format.\nProposalCRMData is the DB/internal format (camelCase); this is the API-facing format." }, "PaymentSettings": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether payment collection is enabled for this proposal" }, "type": { "type": "string", "enum": [ "percentage", "fixed" ], "description": "Payment type (e.g., deposit, full)" }, "deposit_percentage": { "type": "number", "description": "Deposit percentage required (0-100)" }, "deposit_amount": { "type": [ "number", "null" ], "description": "Fixed deposit amount required" }, "frequency": { "type": "string", "description": "Payment frequency schedule" } }, "required": [ "enabled", "type", "deposit_percentage", "deposit_amount", "frequency" ], "additionalProperties": false, "description": "Payment configuration stored in proposals.attrs.settings.payment (This mirrors IntegrationSettings.payment from settings.ts)" }, "CRMProvider": { "type": "string", "enum": [ "pipedrive", "hubspot", "zoho", "gohighlevel" ], "description": "Supported CRM integration provider" }, "PageDesignSettings": { "type": "object", "properties": { "backgroundColor": { "type": "string", "description": "Background color (CSS color value)" }, "fontColor": { "type": "string", "description": "Font/text color (CSS color value)" }, "backgroundImage": { "type": "string", "description": "URL of the background image" }, "backgroundPosition": { "type": "string", "description": "CSS background-position value" }, "backgroundSize": { "type": "string", "description": "CSS background-size value" }, "backgroundRepeat": { "type": "string", "description": "CSS background-repeat value" }, "backgroundAttachment": { "type": "string", "description": "CSS background-attachment value" }, "backgroundOpacity": { "type": "number", "description": "Opacity of the background image (0-1)" } }, "additionalProperties": false, "description": "Visual design settings for a specific page" }, "PageChild": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "group", "description": "Discriminator for PageChild union (set when part of children array)" }, "id": { "type": "string", "description": "Unique group identifier" }, "name": { "type": "string", "description": "Group name/title" }, "description": { "type": "string", "description": "Group description text" }, "isOptional": { "type": "boolean", "description": "Whether this group is optional for the client" }, "isSelected": { "type": "boolean", "description": "Whether this optional group is currently selected" }, "displayCost": { "type": "string", "enum": [ "show_all", "hide_all", "hide_item_costs", "hide_group_cost" ], "description": "Whether to show the cost for this group" }, "selectionType": { "type": "string", "enum": [ "single", "multiple", "loose" ], "description": "How items within this group can be selected (single, multiple, etc.)" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" }, "description": "Array of line items in this group" }, "hideQuantities": { "type": "boolean", "description": "Whether to hide quantity columns" }, "startExpanded": { "type": "boolean", "description": "Whether the group starts expanded in the proposal view" }, "quantity": { "$ref": "#/components/schemas/QuantityConfig" }, "order_key": { "type": "number", "description": "Sort position of the group within the page" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags/labels applied to this group" }, "linkedScopeId": { "type": [ "string", "null" ], "description": "ID of the linked scope of work section" }, "created_at": { "type": "string", "description": "When the group was created (ISO 8601 timestamp)" }, "updated_at": { "type": "string", "description": "When the group was last updated (ISO 8601 timestamp)" }, "metadata": { "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E" }, "archived_at": { "type": [ "string", "null" ], "description": "When the group was archived (ISO 8601 timestamp), or null if active" }, "is_archived": { "type": "boolean", "description": "Whether the group is archived" }, "in_library": { "type": "boolean", "description": "Whether this group belongs to the library (true) or a regular proposal (false/undefined)" } }, "required": [ "displayCost", "id", "isOptional", "isSelected", "kind", "lineItems", "name", "selectionType" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "side_by_side", "description": "Discriminator for PageChild union (set when part of children array)" }, "id": { "type": "string", "description": "Unique identifier for the side-by-side item" }, "name": { "type": "string", "description": "Display name" }, "description": { "type": "string", "description": "Description text" }, "style": { "type": "string", "enum": [ "standard", "comparison" ], "description": "Layout style: 'standard' (default column cards) or 'comparison' (feature comparison grid)" }, "selectionType": { "type": "string", "enum": [ "multiple", "single", "loose" ], "description": "How options can be selected (single, multiple, etc.)" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "number" }, "frequency": { "type": "string" }, "isSelected": { "type": "boolean" }, "includedFeatures": { "type": "array", "items": { "type": "string" }, "description": "Feature IDs included in this column (only used when style === 'comparison')" }, "featureValues": { "$ref": "#/components/schemas/Record%3Cstring%2Cstring%3E", "description": "Per-feature text overrides keyed by feature ID (renders text instead of check/X)" }, "feeType": { "type": "string", "enum": [ "fixed", "text", "none" ], "description": "Fee type: 'fixed' shows price, 'text' shows text override, 'none' hides price" }, "priceTextOverride": { "type": "string", "description": "Text to display instead of price when feeType is 'text'" }, "quantity": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "editableByRecipient": { "type": "boolean" }, "current": { "type": "number" }, "unitLabel": { "type": "string" } }, "required": [ "min", "max", "editableByRecipient" ], "additionalProperties": false, "description": "Quantity configuration for this column" }, "design": { "type": "object", "properties": { "background": { "type": "string" }, "borderWidth": { "type": "number" }, "borderColor": { "type": "string" }, "borderRadius": { "type": "number" }, "buttonColor": { "type": "string" }, "buttonTextColor": { "type": "string" }, "titleColor": { "type": "string" }, "priceColor": { "type": "string" }, "checkmarkColor": { "type": "string" }, "fontColor": { "type": "string" }, "quantityBackgroundColor": { "type": "string" }, "quantityFontColor": { "type": "string" } }, "additionalProperties": false } }, "required": [ "id", "name", "description", "price", "frequency" ], "additionalProperties": false }, "description": "Array of comparison columns" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/SideBySideFeature" }, "description": "Shared feature list (only used when style === 'comparison')" }, "order_key": { "type": "number", "description": "Sort position" }, "containerDesign": { "type": "object", "properties": { "background": { "type": "string" }, "fontColor": { "type": "string" }, "showHeader": { "type": "boolean" }, "sizeModifier": { "type": "string", "enum": [ "compact", "default", "wide" ] }, "borderColor": { "type": "string" }, "borderWidth": { "type": "number" }, "selectionOutlineColor": { "type": "string" } }, "additionalProperties": false, "description": "Visual design settings for the container" }, "featuresColumnDesign": { "type": "object", "properties": { "background": { "type": "string" }, "fontColor": { "type": "string" }, "borderColor": { "type": "string" }, "borderWidth": { "type": "number" }, "borderRadius": { "type": "number" } }, "additionalProperties": false, "description": "Design settings for the features column (only used when style === 'comparison')" }, "headingDesign": { "type": "object", "properties": { "background": { "type": "string" }, "fontColor": { "type": "string" }, "alignment": { "type": "string", "enum": [ "center", "left", "right" ] } }, "additionalProperties": false, "description": "Design settings for headings (only used when style === 'comparison')" }, "syncQuantitiesAcrossColumns": { "type": "boolean", "description": "Whether to sync quantities across all columns" }, "taxExempt": { "type": "boolean", "description": "Whether this side-by-side is exempt from sales tax" }, "markupExempt": { "type": "boolean", "description": "Whether this side-by-side is exempt from scope-level markup" }, "discountExempt": { "type": "boolean", "description": "Whether this side-by-side is exempt from proposal-wide percentage discounts" } }, "required": [ "columns", "id", "kind", "name" ] } ], "description": "Discriminated union for page children (groups and side-by-sides). Both share order_key from the same namespace for interleaved ordering." }, "LineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique line item identifier" }, "name": { "type": "string", "description": "Line item name/title" }, "description": { "type": "string", "description": "HTML content for the item description" }, "price": { "$ref": "#/components/schemas/PriceConfig" }, "isOptional": { "type": "boolean", "description": "Whether this line item is optional for the client" }, "isSelected": { "type": "boolean", "description": "Whether this optional item is currently selected" }, "taxExempt": { "type": "boolean", "description": "Whether this item is exempt from sales tax" }, "markupExempt": { "type": "boolean", "description": "Whether this item is exempt from markup" }, "discountExempt": { "type": "boolean", "description": "Whether this item is exempt from proposal-wide percentage discounts" }, "hidden": { "type": "boolean", "description": "Whether this item is hidden from the client view" }, "hideModifications": { "type": "boolean", "description": "Whether to hide modifications/options for this item" }, "internalNotes": { "type": "string", "description": "Private notes visible only to the proposal creator (not shown to clients)" }, "modificationsLabel": { "type": "string", "description": "Custom label for the modifications section (e.g., \"Options\", \"Add-ons\")" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/Modification" }, "description": "Array of child modifications/options for this line item" }, "startExpanded": { "type": "boolean", "description": "Whether modifications are expanded by default" }, "order_key": { "type": "number", "description": "Sort position within the group" }, "selectionType": { "type": "string", "enum": [ "single", "multiple", "loose" ], "description": "How child modifications can be selected (single, multiple, etc.)" }, "label": { "type": "string", "description": "Custom display label for this line item" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags/labels applied to this item" }, "integrations": { "type": "object", "properties": { "quickbooks": { "type": "object", "properties": { "productId": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "External integration references for this item" }, "created_at": { "type": "string", "description": "When the item was created (ISO 8601 timestamp)" }, "updated_at": { "type": "string", "description": "When the item was last updated (ISO 8601 timestamp)" }, "archived_at": { "type": [ "string", "null" ], "description": "When the item was archived (ISO 8601 timestamp), or null if active" }, "is_archived": { "type": "boolean", "description": "Whether the item is archived" }, "childCount": { "type": "number", "description": "Number of child modifications" }, "parent_id": { "type": [ "string", "null" ], "description": "The public_id of the parent group or scope that this item belongs to" }, "in_library": { "type": "boolean", "description": "Whether this item belongs to the library (true) or a regular proposal (false/undefined)" }, "linkedLibraryItemId": { "type": [ "string", "null" ], "description": "Public ID of the library item this is linked to (templates only)" }, "hasLinkedItems": { "type": "boolean", "description": "Whether this library item has other items linked to it (library items only)" } }, "required": [ "id", "name", "description", "price", "isOptional", "isSelected", "taxExempt", "markupExempt", "discountExempt", "children" ], "additionalProperties": false, "description": "A line item (product or service) within a group" }, "QuantityConfig": { "type": "object", "properties": { "min": { "type": "number", "description": "Minimum quantity allowed" }, "max": { "type": "number", "description": "Maximum quantity allowed" }, "editableByRecipient": { "type": "boolean", "description": "Whether the recipient can edit the quantity" }, "current": { "type": "number", "description": "Current quantity value" }, "unitLabel": { "type": "string", "description": "Custom label for the unit (e.g., \"hours\", \"items\")" } }, "required": [ "min", "max", "editableByRecipient" ], "additionalProperties": false, "description": "Configuration for item quantity settings" }, "SideBySideFeature": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this feature" }, "name": { "type": "string", "description": "Display name of the feature" }, "order_key": { "type": "number", "description": "Sort position" }, "type": { "type": "string", "enum": [ "feature", "heading" ], "description": "Type of row: 'feature' (default) or 'heading'" } }, "required": [ "id", "name", "order_key" ], "additionalProperties": false, "description": "A feature row used in comparison-style side-by-side items" }, "PriceConfig": { "description": "Price configuration - discriminated union of pricing models\nThe 'model' field determines which configuration type is used", "oneOf": [ { "$ref": "#/components/schemas/FixedPriceConfig" }, { "$ref": "#/components/schemas/PercentPriceConfig" }, { "$ref": "#/components/schemas/TextPriceConfig" }, { "$ref": "#/components/schemas/NonePriceConfig" }, { "$ref": "#/components/schemas/HourlyPriceConfig" } ], "discriminator": { "propertyName": "model", "mapping": { "fixed": "#/components/schemas/FixedPriceConfig", "percent": "#/components/schemas/PercentPriceConfig", "text": "#/components/schemas/TextPriceConfig", "none": "#/components/schemas/NonePriceConfig" } } }, "Modification": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the modification" }, "name": { "type": "string", "description": "Name of the modification" }, "description": { "type": "string", "description": "HTML description of the modification" }, "price": { "$ref": "#/components/schemas/PriceConfig", "description": "Price configuration" }, "isOptional": { "type": "boolean", "description": "Whether this modification is optional" }, "isSelected": { "type": "boolean", "description": "Whether this modification is currently selected" }, "taxExempt": { "type": "boolean", "description": "Whether this modification is exempt from tax calculations" }, "markupExempt": { "type": "boolean", "description": "Whether this modification is exempt from markup calculations" }, "discountExempt": { "type": "boolean", "description": "Whether this modification is exempt from percentage-based scope discounts" }, "label": { "type": "string", "description": "Custom label for the modification" }, "kind": { "type": "string", "enum": [ "mod", "mod_divider" ], "description": "Item kind - 'mod' for regular modifications, 'mod_divider' for dividers" }, "selectionType": { "type": "string", "enum": [ "single", "multiple", "loose" ], "description": "Selection type for dividers - affects modifications below the divider" }, "integrations": { "type": "object", "properties": { "quickbooks": { "type": "object", "properties": { "productId": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Integration-specific data" }, "created_at": { "type": "string", "description": "When the modification was created (ISO 8601 timestamp)" }, "updated_at": { "type": "string", "description": "When the modification was last updated (ISO 8601 timestamp)" }, "archived_at": { "type": [ "string", "null" ], "description": "When the modification was archived (ISO 8601 timestamp), or null if active" }, "is_archived": { "type": "boolean", "description": "Whether this modification is archived" } }, "required": [ "id", "name", "price", "isOptional", "isSelected", "taxExempt", "markupExempt", "discountExempt" ], "additionalProperties": false, "description": "A modification (child item) of a line item - represents an option or variant" }, "FixedPriceConfig": { "type": "object", "properties": { "value": { "type": "number", "description": "Price value - required for fixed/percent models. For fixed: amount in cents. For percent: decimal (e.g., 0.15 for 15%)" }, "maxValue": { "type": "number", "description": "Maximum price value for range pricing" }, "isRange": { "type": "boolean", "description": "Whether this represents a price range" }, "quantity": { "anyOf": [ { "$ref": "#/components/schemas/QuantityConfig" }, { "type": "null" } ], "description": "Quantity configuration" }, "discount": { "anyOf": [ { "$ref": "#/components/schemas/LineItemDiscountConfig" }, { "type": "null" } ], "description": "Discount configuration" }, "model": { "type": "string", "const": "fixed", "description": "Pricing model type - must be \"fixed\"" }, "frequency": { "$ref": "#/components/schemas/Frequency", "description": "Billing frequency" } }, "required": [ "model", "frequency" ], "additionalProperties": false, "description": "Fixed price configuration - item has a fixed price per unit" }, "PercentPriceConfig": { "type": "object", "properties": { "value": { "type": "number", "description": "Price value - required for fixed/percent models. For fixed: amount in cents. For percent: decimal (e.g., 0.15 for 15%)" }, "maxValue": { "type": "number", "description": "Maximum price value for range pricing" }, "isRange": { "type": "boolean", "description": "Whether this represents a price range" }, "quantity": { "anyOf": [ { "$ref": "#/components/schemas/QuantityConfig" }, { "type": "null" } ], "description": "Quantity configuration" }, "discount": { "anyOf": [ { "$ref": "#/components/schemas/LineItemDiscountConfig" }, { "type": "null" } ], "description": "Discount configuration" }, "model": { "type": "string", "const": "percent", "description": "Pricing model type - must be \"percent\"" }, "frequency": { "$ref": "#/components/schemas/Frequency", "description": "Billing frequency" }, "percentageApplyTo": { "type": "string", "enum": [ "line", "group", "scope" ], "description": "What the percentage applies to: 'line' (parent line item), 'group' (parent group total), or 'scope' (proposal total)" } }, "required": [ "model", "frequency" ], "additionalProperties": false, "description": "Percentage-based price configuration - item price is a percentage of another value" }, "TextPriceConfig": { "type": "object", "properties": { "value": { "type": "number", "description": "Price value - required for fixed/percent models. For fixed: amount in cents. For percent: decimal (e.g., 0.15 for 15%)" }, "maxValue": { "type": "number", "description": "Maximum price value for range pricing" }, "isRange": { "type": "boolean", "description": "Whether this represents a price range" }, "quantity": { "anyOf": [ { "$ref": "#/components/schemas/QuantityConfig" }, { "type": "null" } ], "description": "Quantity configuration" }, "discount": { "anyOf": [ { "$ref": "#/components/schemas/LineItemDiscountConfig" }, { "type": "null" } ], "description": "Discount configuration" }, "model": { "type": "string", "const": "text", "description": "Pricing model type - must be \"text\"" }, "frequency": { "$ref": "#/components/schemas/Frequency", "description": "Billing frequency" } }, "required": [ "model", "frequency" ], "additionalProperties": false, "description": "Text-based price configuration - price is entered as text (e.g., \"Contact for pricing\")" }, "NonePriceConfig": { "type": "object", "properties": { "value": { "type": "number", "description": "Price value - required for fixed/percent models. For fixed: amount in cents. For percent: decimal (e.g., 0.15 for 15%)" }, "maxValue": { "type": "number", "description": "Maximum price value for range pricing" }, "isRange": { "type": "boolean", "description": "Whether this represents a price range" }, "quantity": { "anyOf": [ { "$ref": "#/components/schemas/QuantityConfig" }, { "type": "null" } ], "description": "Quantity configuration" }, "discount": { "anyOf": [ { "$ref": "#/components/schemas/LineItemDiscountConfig" }, { "type": "null" } ], "description": "Discount configuration" }, "model": { "type": "string", "const": "none", "description": "Pricing model type - must be \"none\"" } }, "required": [ "model" ], "additionalProperties": false, "description": "No price configuration - item has no price" }, "HourlyPriceConfig": { "type": "object", "properties": { "value": { "type": "number", "description": "Price value - required for fixed/percent models. For fixed: amount in cents. For percent: decimal (e.g., 0.15 for 15%)" }, "maxValue": { "type": "number", "description": "Maximum price value for range pricing" }, "isRange": { "type": "boolean", "description": "Whether this represents a price range" }, "quantity": { "anyOf": [ { "$ref": "#/components/schemas/QuantityConfig" }, { "type": "null" } ], "description": "Quantity configuration" }, "discount": { "anyOf": [ { "$ref": "#/components/schemas/LineItemDiscountConfig" }, { "type": "null" } ], "description": "Discount configuration" }, "model": { "type": "string", "const": "hourly", "description": "Pricing model type - must be \"hourly\"" }, "frequency": { "$ref": "#/components/schemas/Frequency", "description": "Billing frequency" }, "hourlyTasks": { "$ref": "#/components/schemas/Record%3Cstring%2C(number%7Cstructure-385897607-4346-4375-385897607-4337-4382-385897607-4322-4383-385897607-4229-4384-385897607-3935-4473-385897607-0-6374%7Cnull)%3E", "description": "Hourly tasks with their hours (single number or range)" }, "hourlyTaskUseRanges": { "type": "boolean", "description": "Whether hourly tasks use ranges" } }, "required": [ "model", "frequency" ], "additionalProperties": false, "description": "Hourly price configuration - item price is calculated from hourly tasks" }, "LineItemDiscountConfig": { "type": "object", "properties": { "added": { "type": "boolean", "description": "Whether the discount has been added" }, "isSelected": { "type": "boolean", "description": "Whether the discount is currently selected/applied" }, "scope": { "type": "string", "enum": [ "unit", "line", "group", "scope" ], "description": "Scope of the discount: 'unit' (per unit), 'line' (entire line), 'group' (entire group), or 'scope' (entire pricing table)" }, "type": { "type": "string", "enum": [ "percentage", "fixed" ], "description": "Discount type: 'percentage' or 'fixed' amount" }, "amount": { "type": "number", "description": "Discount amount - percentage as decimal (e.g., 0.10 for 10%) or fixed amount in cents" } }, "additionalProperties": {}, "description": "Configuration for discounts applied to line items" }, "Frequency": { "type": "string", "enum": [ "once", "monthly", "quarterly", "annually", "weekly", "biweekly", "semi-monthly", "semi-annually" ], "examples": [ "monthly" ], "description": "Billing frequency for recurring items" }, "ProposalDisplayStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "PENDING", "CANCELLED", "WON", "LOST", "EXPIRED" ], "description": "Proposal status" }, "ProposalUser": { "type": "object", "properties": { "id": { "type": "string", "description": "Public user ID" }, "name": { "type": "string", "description": "Full name" }, "email": { "type": "string", "description": "Email address" }, "avatar_url": { "type": [ "string", "null" ], "description": "Avatar image URL" } }, "required": [ "id", "name", "email" ], "additionalProperties": false, "description": "User profile embedded in proposal responses (used for both created_by and updated_by)" }, "ProposalCachedTotals": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code for the cached totals (e.g. \"USD\")" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp when the cached totals were last recalculated" }, "once": { "$ref": "#/components/schemas/ProposalCachedTotalRange", "description": "One-time pricing total range" }, "monthly": { "$ref": "#/components/schemas/ProposalCachedTotalRange", "description": "Monthly recurring pricing total range" }, "quarterly": { "$ref": "#/components/schemas/ProposalCachedTotalRange", "description": "Quarterly recurring pricing total range" }, "annually": { "$ref": "#/components/schemas/ProposalCachedTotalRange", "description": "Annually recurring pricing total range" } }, "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/ProposalCachedTotalRange" }, { "type": "string" }, { "not": {} } ] }, "description": "Cached pricing totals for the proposal" }, "ProposalListItemStatusDetail": { "type": "object", "properties": { "marked_as_won_method": { "type": [ "string", "null" ], "enum": [ "manual", "digital_signature", "acceptance", null ], "description": "Method used to mark the proposal as won" } }, "additionalProperties": false, "description": "Subset of status details relevant to list views" }, "ProposalCachedTotalRange": { "type": "object", "properties": { "min": { "type": "number", "description": "Minimum total amount" }, "max": { "type": "number", "description": "Maximum total amount" } }, "required": [ "min", "max" ], "additionalProperties": false, "description": "A price range with minimum and maximum values" }, "ProposalStatusDetail": { "type": "object", "properties": { "acceptance": { "anyOf": [ { "$ref": "#/components/schemas/ProposalAcceptance" }, { "type": "null" } ], "description": "Details of the proposal acceptance, if accepted via accept button" }, "cancellation_note": { "type": "string", "description": "Note explaining why the proposal was cancelled" }, "closed_proposal_note": { "type": "string", "description": "Note displayed when the proposal is closed (won/lost)" }, "marked_as_won_method": { "type": [ "string", "null" ], "enum": [ "manual", "digital_signature", "acceptance", null ], "description": "Method used to mark the proposal as won" }, "signature_events": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "type", "timestamp" ], "additionalProperties": {} } }, { "type": "null" } ], "description": "Chronological log of signature-related events" }, "signatures": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E" } }, { "type": "null" } ], "description": "Collected digital signatures on the proposal" }, "signed_pdf_url": { "type": [ "string", "null" ], "description": "URL of the signed PDF document, if available" } }, "additionalProperties": false, "description": "Status lifecycle and resolution details for a proposal" }, "ProposalAcceptance": { "type": "object", "properties": { "full_name": { "type": "string" }, "ip_address": { "type": "string" }, "accepted_at": { "type": "string" }, "user_agent": { "type": "string" } }, "required": [ "full_name", "ip_address", "accepted_at" ], "additionalProperties": false, "description": "Acceptance details when a proposal is accepted via the accept button" }, "ProposalIntegrations": { "type": "object", "properties": { "crm": { "anyOf": [ { "$ref": "#/components/schemas/ApiProposalCRMData" }, { "type": "null" } ], "description": "CRM integration data (deal link, provider, metadata)" }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/ProposalPaymentData" }, { "type": "null" } ], "description": "Payment processing configuration and transaction history" } }, "additionalProperties": false, "description": "External integration data bundled on a proposal (CRM, payment, etc.)" }, "ProposalPage": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique page identifier" }, "created_at": { "type": "string", "description": "When the page was created (ISO 8601 timestamp)" }, "updated_at": { "type": "string", "description": "When the page was last updated (ISO 8601 timestamp)" }, "name": { "type": "string", "description": "Page name/title" }, "content": { "type": "string", "description": "Rich text content of the page" }, "order_key": { "type": "number", "description": "Sort position of the page within the proposal" }, "kind": { "type": "string", "description": "Type of page (e.g., content, pricing, signatures)" }, "scopeId": { "type": "string", "description": "ID of the scope of work section this page belongs to" }, "isScopeOfWork": { "type": "boolean", "description": "Whether this page is a scope of work pricing page" }, "isSignaturesPage": { "type": "boolean", "description": "Whether this is the signatures page" }, "screenshotUrl": { "type": [ "string", "null" ], "description": "URL of the page screenshot thumbnail" }, "showCents": { "type": "boolean", "description": "Whether to display cents in price values" }, "salesTaxPercentage": { "type": "string", "description": "Sales tax percentage applied to this page" }, "lineItemsStartExpanded": { "type": "string", "enum": [ "none", "all", "first" ], "description": "Whether line items are expanded by default" }, "selectionType": { "type": "string", "enum": [ "single", "multiple", "loose" ], "description": "How items on this page can be selected" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags/labels applied to this page" }, "metadata": { "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E" }, "markupPercentage": { "type": "string", "description": "Markup percentage applied to items on this page" }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "fixed", "percentage" ] }, "amount": { "type": "string" }, "frequency": { "type": "string" } }, "required": [ "id", "type", "amount", "frequency" ], "additionalProperties": false }, "description": "Discount configurations for this page" }, "hideTotalsTop": { "type": "boolean", "description": "Whether to hide the totals row at the top of the page" }, "hideTotalsBottom": { "type": "boolean", "description": "Whether to hide the totals row at the bottom of the page" }, "labels": { "type": "object", "properties": { "grandTotalLabels": { "$ref": "#/components/schemas/Record%3Cstring%2Cstring%3E" }, "tax": { "type": "string" } }, "additionalProperties": false, "description": "Custom label overrides for this page" }, "displayHeading": { "type": "boolean", "description": "Whether to display the page heading" }, "hideSection": { "type": "boolean", "description": "Whether this section is hidden from view" }, "excludeFromPdf": { "type": "boolean", "description": "Whether to exclude this page from PDF exports" }, "designSettings": { "$ref": "#/components/schemas/PageDesignSettings" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/PageChild" }, "description": "Unified ordered list of groups and side-by-sides (only on scope-of-work pages)" } }, "required": [ "name", "content", "order_key" ], "description": "A page within a proposal. Pages contain the content sections of a proposal." }, "V1SigningData": { "type": "object", "properties": { "document_hash": { "type": [ "string", "null" ] }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/V1SignerStatus" } }, "last_synced_at": { "type": [ "string", "null" ] } }, "additionalProperties": false, "description": "Signing data from a v1 legacy proposal managed by Xodo Sign" }, "V1SignerStatus": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "company", "client" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "forwarded", "bounced", "declined", "removed" ] }, "timestamp": { "type": [ "string", "null" ] }, "forwarded": { "type": "boolean" } }, "required": [ "role", "name", "email", "status" ], "additionalProperties": false, "description": "Status of a signer in the v1 Xodo Sign system" }, "ProposalPaymentData": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/PaymentSettings", "description": "Payment processing configuration" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalPayment" }, "description": "Collected payment transactions" } }, "required": [ "settings", "transactions" ], "additionalProperties": false, "description": "Combined payment data on a proposal: configuration + transaction history. Analogous to ProposalCRMData for CRM integration." }, "ProposalPayment": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount collected" }, "currency": { "type": "string", "description": "Currency code for the payment" }, "percentage": { "type": "number", "description": "Percentage of the proposal total this payment represents" }, "processor": { "type": "string", "const": "stripe", "description": "Payment processor used (e.g., stripe)" }, "processor_payment_id": { "type": "string", "description": "Payment ID from the payment processor" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "payment_type": { "$ref": "#/components/schemas/PaymentType" }, "paid_at": { "type": "string", "description": "When the payment was completed (ISO 8601 timestamp)" }, "processor_session_id": { "type": "string", "description": "Checkout session ID from the payment processor" }, "payer_email": { "type": "string", "description": "Email address of the person who made the payment" }, "payer_name": { "type": "string", "description": "Name of the person who made the payment" }, "metadata": { "type": "object", "properties": { "share_token": { "type": "string" }, "share_link_created_at": { "type": "string", "description": "When the share link was generated (ISO 8601 timestamp)" }, "email_sent_to": { "type": "string" }, "email_sent_at": { "type": "string", "description": "When the email was sent (ISO 8601 timestamp)" }, "created_by_signer": { "type": "boolean" } }, "additionalProperties": false, "description": "Additional payment metadata" }, "created_at": { "type": "string", "description": "When the payment record was created (ISO 8601 timestamp)" }, "updated_at": { "type": "string", "description": "When the payment record was last updated (ISO 8601 timestamp)" } }, "required": [ "amount", "currency", "percentage", "processor", "status", "payment_type", "created_at", "updated_at" ], "additionalProperties": false, "description": "Individual payment record stored in proposals.attrs.payments[]" }, "PaymentStatus": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed", "canceled" ], "description": "Payment status values" }, "PaymentType": { "type": "string", "enum": [ "deposit", "final", "installment" ], "description": "Payment type values (for future multi-payment support)" } }, "responses": { "UnauthorizedError": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Additional error details" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } }, "ForbiddenError": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ], "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Additional error details" } } } } }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient permissions" } } } } }, "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ], "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Validation error details" } } } } }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "Invalid input data", "details": { "name": "Name is required" } } } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Additional error details" } } } } }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } }, "NotFoundOrNotAuthorizedError": { "description": "Not Found - Resource does not exist or access denied", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Additional error details" } } } } }, "example": { "error": { "code": "NOT_FOUND", "message": "Not Authorized or Not Found: Resource {id}" } } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "paths": { "/api/proposals/{id}/analytics": { "get": { "operationId": "GetProposalAnalytics", "summary": "Get analytics events for a proposal", "description": "Retrieve analytics events for a specific proposal. Requires authentication and org access.", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" }, { "in": "query", "name": "event_type", "schema": { "type": "string", "enum": [ "proposal_viewed", "proposal_sent", "status_changed", "proposal_signed", "pdf_viewed", "signature_request_sent" ] }, "description": "Filter by event type" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date-time" }, "description": "Filter events from this date onwards" }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date-time" }, "description": "Filter events up to this date" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Maximum number of events to return" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of events to skip for pagination" } ], "responses": { "200": { "description": "Analytics events retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "event_timestamp": { "type": "string", "format": "date-time" }, "user": { "type": "object", "nullable": true, "properties": { "public_id": { "type": "string" }, "email": { "type": "string" }, "full_name": { "type": "string", "nullable": true } } }, "metadata": { "type": "object" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}/archive": { "post": { "operationId": "ArchiveProposal", "summary": "Archive a proposal", "description": "Archive a proposal by setting its archived_at timestamp. Archived proposals are excluded from default listings and become read-only.", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "responses": { "204": { "description": "Proposal archived successfully" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Not authorized to archive this proposal", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not authorized to archive this proposal" } } } } } }, "404": { "description": "Proposal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Proposal not found" } } } } } }, "409": { "description": "Proposal is already archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Proposal is already archived" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}/bulk-archive": { "post": { "operationId": "BulkArchiveItems", "summary": "Archive multiple items in a proposal", "description": "Archive multiple items (line items, groups) from a proposal", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "itemIds" ], "properties": { "itemIds": { "type": "array", "items": { "type": "string" }, "description": "Array of item IDs to archive", "example": [ "abcdefgh1234", "ijklmnop5678" ] } } } } } }, "responses": { "200": { "description": "Items archived successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "archivedCount": { "type": "integer", "description": "Number of items successfully archived", "example": 3 }, "message": { "type": "string", "description": "Success message", "example": "Successfully archived 3 items" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Array of error messages for failed items (only present if some items failed)" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}/duplicate": { "post": { "operationId": "DuplicateProposal", "summary": "Duplicate a proposal", "description": "Create a complete copy of an existing proposal with all its groups, items, and pages", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the duplicated proposal. Default: \"Copy of {original name}\"", "example": "Copy of Q1 2024 Proposal" } } } } } }, "responses": { "201": { "description": "Proposal duplicated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the newly created proposal" } } } } } } } }, "400": { "description": "Validation error" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Proposal not found" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}/pdf": { "post": { "operationId": "GenerateProposalPDF", "summary": "Generate proposal PDF", "description": "Generate a PDF document for the specified proposal. Returns the PDF as a binary download.", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "PDF generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Proposal not found" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}": { "get": { "operationId": "GetProposal", "summary": "Get a single proposal", "description": "Retrieve detailed information about a specific proposal including all items and groups", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "responses": { "200": { "description": "Proposal retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDetail" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Proposal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "NOT_FOUND" }, "message": { "type": "string", "example": "Proposal not found" } } } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "UpdateProposal", "summary": "Update a proposal", "description": "Update proposal details such as name, description, or client information", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProposalApiInput" } } } }, "responses": { "200": { "description": "Proposal updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalListItem" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Proposal not found" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "DeleteProposal", "summary": "Delete a proposal", "description": "Delete a proposal and all its associated items. The proposal will no longer appear in listings.", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "responses": { "204": { "description": "Proposal deleted successfully" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundOrNotAuthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}/star": { "post": { "operationId": "StarProposal", "summary": "Star a proposal", "description": "Star a proposal for the current user. Starred proposals appear first in listings. This operation is idempotent - starring an already-starred proposal has no effect.", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "responses": { "200": { "description": "Proposal starred successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_starred": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundOrNotAuthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}/unarchive": { "post": { "operationId": "UnarchiveProposal", "summary": "Unarchive a proposal", "description": "Unarchive a proposal by clearing its archived_at timestamp. The proposal will return to active status and become editable again.", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "responses": { "204": { "description": "Proposal unarchived successfully" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Not authorized to unarchive this proposal", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not authorized to unarchive this proposal" } } } } } }, "404": { "description": "Proposal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Proposal not found" } } } } } }, "409": { "description": "Proposal is not archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Proposal is not archived" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals/{id}/unstar": { "post": { "operationId": "UnstarProposal", "summary": "Unstar a proposal", "description": "Remove the star from a proposal for the current user. This operation is idempotent - unstarring a proposal that is not starred has no effect.", "tags": [ "Proposals" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Proposal ID", "example": "zw5FD5HGcfE3" } ], "responses": { "200": { "description": "Proposal unstarred successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_starred": { "type": "boolean", "example": false } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundOrNotAuthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/proposals": { "get": { "operationId": "ListProposals", "summary": "List all proposals", "description": "Retrieve a paginated list of proposals for the authenticated user's organization", "tags": [ "Proposals" ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for pagination" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Number of items per page" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search term to filter proposals by name or client", "example": "Website" }, { "in": "query", "name": "sort", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "status" ], "default": "created_at" }, "description": "Field to sort by" }, { "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "draft", "sent", "won", "lost", "cancelled" ] }, "description": "Filter by proposal status" }, { "in": "query", "name": "created_by", "schema": { "type": "string" }, "description": "Filter by creator's public_id" }, { "in": "query", "name": "archived", "schema": { "type": "string", "enum": [ false, true, "any" ], "default": false }, "description": "Filter by archive status (false=non-archived, true=archived only, any=both)", "example": "false" } ], "responses": { "200": { "description": "Successful response with proposals list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "CreateProposal", "summary": "Create a new proposal", "description": "Create a new proposal for the user's organization", "tags": [ "Proposals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProposalApiInput" } } } }, "responses": { "201": { "description": "Proposal created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateProposalResponse" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "tags": [] }