API Docs

Quick Links

Base URLhttps://web.smartpricingtable.com/api

Beta

This API is in beta. Endpoints and response shapes may change as we iterate. For questions or feedback, email support@smartpricingtable.com.

Authentication

API Key Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can create and manage API keys from your profile settings.

Pagination

List endpoints return paginated results. Include page and limit query parameters to control which page of results you receive.

Request Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (starts at 1)
limit	integer	20	Items per page (1–100)

Response Format

Every list response includes a pagination object alongside the data array:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Proposals(16)

GET/proposals

ListProposals

Retrieve a paginated list of proposals for the authenticated user's organization. Templates are excluded by default. Pass `is_template=true` to list reusable templates instead of regular proposals (not both). Use a returned template's `id` with `POST /api/proposals` (`templateId`) to create a proposal from that template.

Query Parameters

archivedenum

falsedefaulttrueany

Filter by archive status (false=non-archived, true=archived only, any=both)

created_bystring

Filter by creator's public_id

is_templateboolean

Default: false. When true, return only template proposals (reusable templates). When omitted or false, templates are excluded and only regular proposals are returned.

limitinteger

Default: 20. Number of items per page

orderenum

descdefaultasc

Sort order

pageinteger

Default: 1. Page number for pagination

searchstring

Search term to filter proposals by name or client

sortenum

created_atdefaultupdated_atnamestatusclient_namesentexpiring_oncompletedlast_activity

Field to sort by. Date sorts (sent, expiring_on, completed, last_activity) push proposals missing that date to the end; last_activity is the most recent recipient-facing engagement.

statusenum

draftsentwonlostcancelled

Filter by proposal status

Responses

200Successful response with proposals list

dataarray of ProposalListItem

allRecipientsSignedboolean

True once all recipient signers (client + additional) have signed, meaning only the company is left to sign. Used by getDisplayStatus() to suppress the EXPIRED badge — expiration is a recipient-only concept.

archivedboolean

Whether the proposal is archived

archived_atnullable string

ISO 8601 timestamp when the proposal was archived, or null if not archived

cached_totalsnullable object

Cached pricing totals for quick display

completed_atnullable string

ISO 8601 timestamp all recipient signers completed (attrs.recipientsCompletedAt)

created_atstring

ISO 8601 timestamp when the proposal was created

created_bynullable ProposalUser

User who created the proposal

crm_linkednullable object

CRM link info when proposal is linked to a CRM contact/deal

idstring

Unique identifier for the proposal

is_starredboolean

Whether the current user has starred this proposal

is_templateboolean

Whether this proposal is a reusable template. List templates via GET /api/proposals?is_template=true.

last_activity_atnullable string

ISO 8601 timestamp of the most recent recipient-facing activity (view, selection, signing, payment). Powers the "Last Active" sort.

namestring

Display name of the proposal

notesnullable string

Private, admin-only rich-text note attached to the proposal (HTML). Never shown to recipients. Empty/undefined when no note has been added.

proposal_numbernullable string

Tenant-scoped proposal number when set (attrs.proposalNumber).

sent_atnullable string

ISO 8601 timestamp the proposal was sent to the recipient (attrs.timestamps.sent)

settingsobject

Display and behavior settings for the proposal (API format, snake_case)

statusenum

Current workflow status of the proposal

DRAFTSENTPENDINGCANCELLEDON_HOLDWONLOSTEXPIRED

status_detailobject

Status lifecycle details (subset relevant to list views)

tagsarray of string

Tags assigned to this proposal

updated_atstring

ISO 8601 timestamp when the proposal was last updated

updated_bynullable ProposalUser

User who last updated the proposal

paginationobject

Example

{
  "data": [
    {
      "created_at": "example-string",
      "created_by": {
        "email": "example-string",
        "id": "example-string",
        "name": "example-string",
        "avatar_url": "example-string"
      },
      "id": "example-string",
      "name": "example-string",
      "status": "DRAFT",
      "updated_at": "example-string",
      "updated_by": {
        "email": "example-string",
        "id": "example-string",
        "name": "example-string",
        "avatar_url": "example-string"
      },
      "allRecipientsSigned": true,
      "archived": true,
      "archived_at": "example-string",
      "cached_totals": {
        "annually": {
          "max": 100,
          "min": 100
        },
        "currency": "example-string",
        "monthly": {
          "max": 100,
          "min": 100
        },
        "once": {
          "max": 100,
          "min": 100
        },
        "quarterly": {
          "max": 100,
          "min": 100
        },
        "updated_at": "example-string"
      },
      "completed_at": "example-string",
      "crm_linked": {
        "provider": "example-string",
        "recipient_name": "example-string"
      },
      "is_starred": true,
      "is_template": true,
      "last_activity_at": "example-string",
      "notes": "example-string",
      "proposal_number": "example-string",
      "sent_at": "example-string",
      "settings": {
        "avoid_line_item_page_breaks": true,
        "currency": "example-string",
        "disable_proposal_access": true,
        "email_draft": {
          "last_saved": "example-string",
          "message": "example-string",
          "recipients": "example-string",
          "subject": "example-string"
        },
        "expiring_on": "example-string",
        "hide_pdf_download": true,
        "hide_unselected_from_recipient": true,
        "include_modifications_in_line_item_price": true,
        "lock_selections_from_recipient": true,
        "notifications": {
          "override_account_defaults": true,
          "rules": [
            {}
          ]
        },
        "proposal_continuous_scroll": true,
        "recipient": {
          "address": "example-string",
          "contact": {
            "email": "example-string",
            "name": "example-string",
            "phone": "example-string"
          },
          "name": "example-string",
          "website": "example-string"
        },
        "signing": {
          "acceptance_method": "digital_signatures",
          "additional_signers": [
            {}
          ],
          "company_signer": "example-string",
          "custom_company_signer_email": "example-string",
          "custom_company_signer_name": "example-string",
          "is_contact_signer": true,
          "is_multiple_signers": true,
          "override_signature_page_defaults": true,
          "recipient_signer": {
            "email": "example-string",
            "full_name": "example-string"
          },
          "signature_page_agreement_text": "example-string",
          "signature_page_business_label": "example-string",
          "signature_page_client_label": "example-string",
          "signature_page_company_label": "example-string",
          "signature_page_date_label": "example-string",
          "signature_page_labels_captured": true,
          "use_accept": true
        }
      },
      "status_detail": {
        "marked_as_won_method": "manual"
      },
      "tags": [
        "example-string"
      ]
    }
  ]
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals

CreateProposal

Create a new proposal for the user's organization. To create from a template, pass `templateId` with a template public ID from `GET /api/proposals?is_template=true`. To create a reusable template instead of a proposal, set `is_template` to true.

Request Body

object

Example

null

Responses

201Proposal created successfully

dataobject

idstring

Unique identifier for the created proposal

Example

{
  "data": {
    "id": "example-string"
  }
}

400Validation error

errorobject

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "example-string",
    "details": {}
  }
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

GET/proposals/{id}

GetProposal

Retrieve detailed information about a specific proposal including all items and groups. For an importable backup matching More → Export as JSON in the app, use GET /api/proposals/{id}/export instead.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

200Proposal retrieved successfully

object

Example

null

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

errorobject

Example

{
  "error": {
    "code": "example-string",
    "message": "example-string"
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

PATCH/proposals/{id}

UpdateProposal

Update proposal details such as name, description, or client information

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

object

Example

null

Responses

200Proposal updated successfully

ProposalListItem

allRecipientsSignedboolean

archivedboolean

Whether the proposal is archived

archived_atnullable string

ISO 8601 timestamp when the proposal was archived, or null if not archived

cached_totalsnullable object

Cached pricing totals for quick display

completed_atnullable string

ISO 8601 timestamp all recipient signers completed (attrs.recipientsCompletedAt)

created_atstring

ISO 8601 timestamp when the proposal was created

created_bynullable ProposalUser

User who created the proposal

crm_linkednullable object

CRM link info when proposal is linked to a CRM contact/deal

idstring

Unique identifier for the proposal

is_starredboolean

Whether the current user has starred this proposal

is_templateboolean

Whether this proposal is a reusable template. List templates via GET /api/proposals?is_template=true.

last_activity_atnullable string

ISO 8601 timestamp of the most recent recipient-facing activity (view, selection, signing, payment). Powers the "Last Active" sort.

namestring

Display name of the proposal

notesnullable string

Private, admin-only rich-text note attached to the proposal (HTML). Never shown to recipients. Empty/undefined when no note has been added.

proposal_numbernullable string

Tenant-scoped proposal number when set (attrs.proposalNumber).

sent_atnullable string

ISO 8601 timestamp the proposal was sent to the recipient (attrs.timestamps.sent)

settingsobject

Display and behavior settings for the proposal (API format, snake_case)

statusenum

Current workflow status of the proposal

DRAFTSENTPENDINGCANCELLEDON_HOLDWONLOSTEXPIRED

status_detailobject

Status lifecycle details (subset relevant to list views)

tagsarray of string

Tags assigned to this proposal

updated_atstring

ISO 8601 timestamp when the proposal was last updated

updated_bynullable ProposalUser

User who last updated the proposal

Example

{
  "created_at": "example-string",
  "created_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "id": "example-string",
  "name": "example-string",
  "status": "DRAFT",
  "updated_at": "example-string",
  "updated_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "allRecipientsSigned": true,
  "archived": true,
  "archived_at": "example-string",
  "cached_totals": {
    "annually": {
      "max": 100,
      "min": 100
    },
    "currency": "example-string",
    "monthly": {
      "max": 100,
      "min": 100
    },
    "once": {
      "max": 100,
      "min": 100
    },
    "quarterly": {
      "max": 100,
      "min": 100
    },
    "updated_at": "example-string"
  },
  "completed_at": "example-string",
  "crm_linked": {
    "provider": "example-string",
    "recipient_name": "example-string"
  },
  "is_starred": true,
  "is_template": true,
  "last_activity_at": "example-string",
  "notes": "example-string",
  "proposal_number": "example-string",
  "sent_at": "example-string",
  "settings": {
    "avoid_line_item_page_breaks": true,
    "currency": "example-string",
    "disable_proposal_access": true,
    "email_draft": {
      "last_saved": "example-string",
      "message": "example-string",
      "recipients": "example-string",
      "subject": "example-string"
    },
    "expiring_on": "example-string",
    "hide_pdf_download": true,
    "hide_unselected_from_recipient": true,
    "include_modifications_in_line_item_price": true,
    "lock_selections_from_recipient": true,
    "notifications": {
      "override_account_defaults": true,
      "rules": [
        {
          "emails": [
            "example-string"
          ],
          "event": "proposal_sent",
          "id": "example-string"
        }
      ]
    },
    "proposal_continuous_scroll": true,
    "recipient": {
      "address": "example-string",
      "contact": {
        "email": "example-string",
        "name": "example-string",
        "phone": "example-string"
      },
      "name": "example-string",
      "website": "example-string"
    },
    "signing": {
      "acceptance_method": "digital_signatures",
      "additional_signers": [
        {
          "email": "example-string",
          "full_name": "example-string",
          "id": "example-string",
          "role": "example-string"
        }
      ],
      "company_signer": "example-string",
      "custom_company_signer_email": "example-string",
      "custom_company_signer_name": "example-string",
      "is_contact_signer": true,
      "is_multiple_signers": true,
      "override_signature_page_defaults": true,
      "recipient_signer": {
        "email": "example-string",
        "full_name": "example-string"
      },
      "signature_page_agreement_text": "example-string",
      "signature_page_business_label": "example-string",
      "signature_page_client_label": "example-string",
      "signature_page_company_label": "example-string",
      "signature_page_date_label": "example-string",
      "signature_page_labels_captured": true,
      "use_accept": true
    }
  },
  "status_detail": {
    "marked_as_won_method": "manual"
  },
  "tags": [
    "example-string"
  ]
}

400Validation error

errorobject

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "example-string",
    "details": {}
  }
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

DELETE/proposals/{id}

DeleteProposal

Delete a proposal and all its associated items. The proposal will no longer appear in listings.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

204Proposal deleted successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Not Found - Resource does not exist or access denied

errorobject

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

GET/proposals/{id}/analytics

GetProposalAnalytics

Retrieve analytics events for a specific proposal. Requires authentication and membership in the proposal's organization (or platform admin).

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Query Parameters

end_datestring

Filter events up to this date

event_typeenum

proposal_viewedproposal_sentstatus_changedproposal_signedpdf_viewedsignature_request_sent

Filter by event type

limitinteger

Default: 50. Maximum number of events to return

offsetinteger

Default: 0. Number of events to skip for pagination

start_datestring

Filter events from this date onwards

Responses

200Analytics events retrieved successfully

dataarray of object

event_timestampstring

event_typestring

idstring

metadataobject

userobject

Example

{
  "data": [
    {
      "event_timestamp": "2024-01-20T15:30:00Z",
      "event_type": "example-string",
      "id": "example-string",
      "metadata": {},
      "user": {
        "email": "example-string",
        "full_name": "example-string",
        "public_id": "example-string"
      }
    }
  ]
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/archive

ArchiveProposal

Archive a proposal by setting its archived_at timestamp. Archived proposals are excluded from default listings and become read-only.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

204Proposal archived successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Not authorized to archive this proposal

errorstring

Example

{
  "error": "example-string"
}

404Proposal not found

errorstring

Example

{
  "error": "example-string"
}

409Proposal is already archived

errorstring

Example

{
  "error": "example-string"
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/bulk-archive

BulkArchiveItems

Archive multiple items (line items, groups) from a proposal

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

itemIdsarray of stringrequired

Array of item IDs to archive

Example

{
  "itemIds": [
    "example-string"
  ]
}

Responses

200Items archived successfully

archivedCountinteger

Number of items successfully archived

errorsarray of string

Array of error messages for failed items (only present if some items failed)

messagestring

Success message

Example

{
  "errors": [
    "example-string"
  ],
  "message": "example-string"
}

400Validation error

errorobject

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "example-string",
    "details": {}
  }
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/duplicate

DuplicateProposal

Create a complete copy of an existing proposal with all its groups, items, and pages

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

namestring

Name for the duplicated proposal. Default: "Copy of {original name}"

Example

{
  "name": "example-string"
}

Responses

201Proposal duplicated successfully

dataobject

idstring

ID of the newly created proposal

Example

{
  "data": {
    "id": "example-string"
  }
}

400Validation error

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

GET/proposals/{id}/export

ExportProposalJSON

Download a proposal or template as the same importable JSON file produced by More → Export as JSON in the app. Save the response body and import it with Create Proposal → Import from JSON — no transformation needed. The response is the export object itself (not wrapped in a data envelope). Non-portable fields such as signature state, payment sessions, and email drafts are stripped, and status is set to DRAFT, matching the in-app export.

Path Parameters

idstringrequired

Proposal or template ID

e.g., zw5FD5HGcfE3

Responses

200Importable proposal or template JSON — the same file you get from More → Export as JSON in the app. Ready to import via Create Proposal → Import from JSON.

designobject

Design settings included in the export

idstring

Source proposal or template ID

is_templateboolean

Whether this export is a template

namestring

Proposal or template name

pagesarray of object

Pages, including scope-of-work content, groups, and line items

settingsobject

Proposal settings included in the export

statusstring

Always DRAFT in exports

Example

{
  "name": "example-string",
  "pages": [
    {}
  ],
  "design": {},
  "id": "example-string",
  "is_template": true,
  "settings": {},
  "status": "example-string"
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found or not authorized

errorobject

Example

{
  "error": {
    "code": "example-string",
    "message": "example-string"
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/items

PostProposalsItems

Create a brand-new line item, group, or side-by-side directly inside a proposal (not copied from the library). A line item is added to a group (target_group_id, or the first group by default); a group or side-by-side is added under a Scope of Work page (scope_of_work_page_id, or the first one by default). Pass after_item_id / before_item_id to position the new item relative to an existing one — it then inherits that item's parent.

Path Parameters

idstringrequired

Public ID of the proposal.

Request Body

typeenumrequired

The kind of item to create.

line_itemgroupside_by_side

namestringrequired

Display name of the item.

descriptionstring

Optional rich-text/HTML description (stored as the item's content).

priceobject

Required for type=line_item. Pricing definition.

optionalboolean

Whether the item is optional (client can toggle it).

selectedboolean

Whether an optional item is selected by default.

tagsarray of string

Tags to attach to the item.

target_group_idstring

For type=line_item. Group to add into (default first group).

scope_of_work_page_idstring

For type=group or side_by_side. Scope of Work page to add under (default first SOW page).

columnsarray of object

Required for type=side_by_side. The selectable packages/columns. Column ids are generated server-side if omitted.

featuresarray of object

For type=side_by_side comparison style — the feature rows.

selection_typeenum

For type=side_by_side. How many columns a client may select (default loose).

singlemultipleloose

styleenum

For type=side_by_side. Layout style (default standard).

standardcomparison

after_item_idstring

Place the new item immediately after this existing item (a line item id for type=line_item; a group/side-by-side id for type=group). Inherits that item's parent. Mutually exclusive with before_item_id.

before_item_idstring

Place the new item immediately before this existing item.

order_keynumber

Optional explicit ordering position. Defaults to appending at the end.

Example

{
  "name": "example-string",
  "type": "line_item",
  "after_item_id": "example-string",
  "before_item_id": "example-string",
  "columns": [
    {
      "name": "example-string",
      "description": "example-string",
      "feeType": "fixed",
      "frequency": "example-string",
      "includedFeatures": [
        "example-string"
      ],
      "isSelected": true,
      "price": 100
    }
  ],
  "description": "example-string",
  "features": [
    {
      "name": "example-string",
      "order_key": 100
    }
  ],
  "optional": true,
  "order_key": 100,
  "price": {
    "frequency": "once",
    "model": "fixed",
    "quantity": {
      "current": 100,
      "max": 100,
      "min": 100,
      "unitLabel": "example-string"
    },
    "value": 100
  },
  "scope_of_work_page_id": "example-string",
  "selected": true,
  "selection_type": "single",
  "style": "standard",
  "tags": [
    "example-string"
  ],
  "target_group_id": "example-string"
}

Responses

201Item created.

dataobject

idstring

namestring

order_keynumber

typestring

successboolean

Example

{
  "data": {
    "id": "example-string",
    "name": "example-string",
    "order_key": 100,
    "type": "example-string"
  },
  "success": true
}

400Invalid request (bad type, missing/invalid fields, or no valid parent).

403Not authorized to edit the proposal.

404Proposal (or referenced parent/position item) not found.

POST/proposals/{id}/library-insertions

PostProposalsLibraryInsertions

Copies a saved library item (line item, group, page, or side-by-side) into the specified proposal. The library item and the target proposal must belong to the same organization. The copy is always a deep, autonomous copy — it does not stay linked to or synced with the library source. Library content is never modified by this operation.

Path Parameters

idstringrequired

Public ID of the target proposal.

Request Body

typeenumrequired

The kind of library item to insert.

line_itemgrouppageside_by_side

library_item_idstringrequired

Public ID of the library item to copy.

target_group_idstring

For type=line_item only. Public ID of the group in the target proposal to add the line item to. Defaults to the first group in the proposal.

scope_of_work_page_idstring

For type=group or side_by_side. Public ID of the Scope of Work page to insert under. Defaults to the first Scope of Work page.

after_item_idstring

Place the new item immediately after this existing item. The new item inherits that item's parent (group for a line item; page for a group/side-by-side) and is given a midpoint order_key. Overrides target_group_id / scope_of_work_page_id. Mutually exclusive with before_item_id.

before_item_idstring

Place the new item immediately before this existing item. Same rules as after_item_id. Mutually exclusive with it.

order_keynumber

Optional explicit ordering position. Defaults to appending at the end.

Example

{
  "library_item_id": "example-string",
  "type": "line_item",
  "after_item_id": "example-string",
  "before_item_id": "example-string",
  "order_key": 100,
  "scope_of_work_page_id": "example-string",
  "target_group_id": "example-string"
}

Responses

201Library item inserted into the proposal.

dataobject

idstring

namestring

order_keynumber

typestring

successboolean

Example

{
  "data": {
    "id": "example-string",
    "name": "example-string",
    "order_key": 100,
    "type": "example-string"
  },
  "success": true
}

400Invalid request (missing/invalid type or required target).

403Not authorized to edit the target proposal.

404Proposal or library item not found (or not in the same organization).

POST/proposals/{id}/pdf

GenerateProposalPDF

Generate a PDF document for the specified proposal. Returns the PDF as a binary download.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

No properties

Example

{}

Responses

200PDF generated successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/star

StarProposal

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.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

200Proposal starred successfully

is_starredboolean

Example

{
  "is_starred": true
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Not Found - Resource does not exist or access denied

errorobject

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/unarchive

UnarchiveProposal

Unarchive a proposal by clearing its archived_at timestamp. The proposal will return to active status and become editable again.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

204Proposal unarchived successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Not authorized to unarchive this proposal

errorstring

Example

{
  "error": "example-string"
}

404Proposal not found

errorstring

Example

{
  "error": "example-string"
}

409Proposal is not archived

errorstring

Example

{
  "error": "example-string"
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/unstar

UnstarProposal

Remove the star from a proposal for the current user. This operation is idempotent - unstarring a proposal that is not starred has no effect.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

200Proposal unstarred successfully

is_starredboolean

Example

{
  "is_starred": true
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Not Found - Resource does not exist or access denied

errorobject

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

Schemas

Item Types

ProposalListItem7 required

Used by: ListProposals (response 200)·UpdateProposal (response 200)

Summary of a proposal for use in list views

idstringrequired

Unique identifier for the proposal

statusenumrequired

Current workflow status of the proposal

DRAFTSENTPENDINGCANCELLEDON_HOLDWONLOSTEXPIRED

namestringrequired

Display name of the proposal

created_bynullable ProposalUserrequired

User who created the proposal

updated_bynullable ProposalUserrequired

User who last updated the proposal

created_atstringrequired

ISO 8601 timestamp when the proposal was created

updated_atstringrequired

ISO 8601 timestamp when the proposal was last updated

archivedboolean

Whether the proposal is archived

archived_atnullable string

ISO 8601 timestamp when the proposal was archived, or null if not archived

settingsobject

Display and behavior settings for the proposal (API format, snake_case)

is_templateboolean

Whether this proposal is a reusable template. List templates via GET /api/proposals?is_template=true.

is_starredboolean

Whether the current user has starred this proposal

cached_totalsnullable object

Cached pricing totals for quick display

status_detailobject

Status lifecycle details (subset relevant to list views)

allRecipientsSignedboolean

sent_atnullable string

ISO 8601 timestamp the proposal was sent to the recipient (attrs.timestamps.sent)

completed_atnullable string

ISO 8601 timestamp all recipient signers completed (attrs.recipientsCompletedAt)

last_activity_atnullable string

ISO 8601 timestamp of the most recent recipient-facing activity (view, selection, signing, payment). Powers the "Last Active" sort.

crm_linkednullable object

CRM link info when proposal is linked to a CRM contact/deal

tagsarray of string

Tags assigned to this proposal

notesnullable string

Private, admin-only rich-text note attached to the proposal (HTML). Never shown to recipients. Empty/undefined when no note has been added.

proposal_numbernullable string

Tenant-scoped proposal number when set (attrs.proposalNumber).

Example

{
  "created_at": "example-string",
  "created_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "id": "example-string",
  "name": "example-string",
  "status": "DRAFT",
  "updated_at": "example-string",
  "updated_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "allRecipientsSigned": true,
  "archived": true,
  "archived_at": "example-string",
  "cached_totals": {
    "annually": {
      "max": 100,
      "min": 100
    },
    "currency": "example-string",
    "monthly": {
      "max": 100,
      "min": 100
    },
    "once": {
      "max": 100,
      "min": 100
    },
    "quarterly": {
      "max": 100,
      "min": 100
    },
    "updated_at": "example-string"
  },
  "completed_at": "example-string",
  "crm_linked": {
    "provider": "example-string",
    "recipient_name": "example-string"
  },
  "is_starred": true,
  "is_template": true,
  "last_activity_at": "example-string",
  "notes": "example-string",
  "proposal_number": "example-string",
  "sent_at": "example-string",
  "settings": {
    "avoid_line_item_page_breaks": true,
    "currency": "example-string",
    "disable_proposal_access": true,
    "email_draft": {
      "last_saved": "example-string",
      "message": "example-string",
      "recipients": "example-string",
      "subject": "example-string"
    },
    "expiring_on": "example-string",
    "hide_pdf_download": true,
    "hide_unselected_from_recipient": true,
    "include_modifications_in_line_item_price": true,
    "lock_selections_from_recipient": true,
    "notifications": {
      "override_account_defaults": true,
      "rules": [
        {
          "emails": [
            "example-string"
          ],
          "event": "proposal_sent",
          "id": "example-string"
        }
      ]
    },
    "proposal_continuous_scroll": true,
    "recipient": {
      "address": "example-string",
      "contact": {
        "email": "example-string",
        "name": "example-string",
        "phone": "example-string"
      },
      "name": "example-string",
      "website": "example-string"
    },
    "signing": {
      "acceptance_method": "digital_signatures",
      "additional_signers": [
        {
          "email": "example-string",
          "full_name": "example-string",
          "id": "example-string",
          "role": "example-string"
        }
      ],
      "company_signer": "example-string",
      "custom_company_signer_email": "example-string",
      "custom_company_signer_name": "example-string",
      "is_contact_signer": true,
      "is_multiple_signers": true,
      "override_signature_page_defaults": true,
      "recipient_signer": {
        "email": "example-string",
        "full_name": "example-string"
      },
      "signature_page_agreement_text": "example-string",
      "signature_page_business_label": "example-string",
      "signature_page_client_label": "example-string",
      "signature_page_company_label": "example-string",
      "signature_page_date_label": "example-string",
      "signature_page_labels_captured": true,
      "use_accept": true
    }
  },
  "status_detail": {
    "marked_as_won_method": "manual"
  },
  "tags": [
    "example-string"
  ]
}

Other

ProposalCachedTotalRange2 required

Used by: ProposalListItem.cached_totals.anyOf[0].annually·ProposalListItem.cached_totals.anyOf[0].monthly·ProposalListItem.cached_totals.anyOf[0].once·ProposalListItem.cached_totals.anyOf[0].quarterly

A price range with minimum and maximum values

minnumberrequired

Minimum total amount

maxnumberrequired

Maximum total amount

Example

{
  "max": 100,
  "min": 100
}

ProposalUser3 required

Used by: ProposalListItem.created_by.anyOf[0]·ProposalListItem.updated_by.anyOf[0]

User profile embedded in proposal responses (used for both created_by and updated_by)

idstringrequired

Public user ID

namestringrequired

Full name

emailstringrequired

Email address

avatar_urlnullable string

Avatar image URL

Example

{
  "email": "example-string",
  "id": "example-string",
  "name": "example-string",
  "avatar_url": "example-string"
}

API Docs

Quick Links

Authentication Pagination OpenAPI Spec

Endpoints

Schemas

Base URLhttps://web.smartpricingtable.com/api

View OpenAPI Spec

Beta

This API is in beta. Endpoints and response shapes may change as we iterate. For questions or feedback, email support@smartpricingtable.com.

Authentication

API Key Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can create and manage API keys from your profile settings.

Pagination

List endpoints return paginated results. Include page and limit query parameters to control which page of results you receive.

Request Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (starts at 1)
limit	integer	20	Items per page (1–100)

Response Format

Every list response includes a pagination object alongside the data array:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Proposals(16)

GET/proposals

ListProposals

Query Parameters

archivedenum

falsedefaulttrueany

Filter by archive status (false=non-archived, true=archived only, any=both)

created_bystring

Filter by creator's public_id

is_templateboolean

Default: false. When true, return only template proposals (reusable templates). When omitted or false, templates are excluded and only regular proposals are returned.

limitinteger

Default: 20. Number of items per page

orderenum

descdefaultasc

Sort order

pageinteger

Default: 1. Page number for pagination

searchstring

Search term to filter proposals by name or client

sortenum

created_atdefaultupdated_atnamestatusclient_namesentexpiring_oncompletedlast_activity

Field to sort by. Date sorts (sent, expiring_on, completed, last_activity) push proposals missing that date to the end; last_activity is the most recent recipient-facing engagement.

statusenum

draftsentwonlostcancelled

Filter by proposal status

Responses

200Successful response with proposals list

dataarray of ProposalListItem

allRecipientsSignedboolean

archivedboolean

Whether the proposal is archived

archived_atnullable string

ISO 8601 timestamp when the proposal was archived, or null if not archived

cached_totalsnullable object

Cached pricing totals for quick display

completed_atnullable string

ISO 8601 timestamp all recipient signers completed (attrs.recipientsCompletedAt)

created_atstring

ISO 8601 timestamp when the proposal was created

created_bynullable ProposalUser

User who created the proposal

crm_linkednullable object

CRM link info when proposal is linked to a CRM contact/deal

idstring

Unique identifier for the proposal

is_starredboolean

Whether the current user has starred this proposal

is_templateboolean

Whether this proposal is a reusable template. List templates via GET /api/proposals?is_template=true.

last_activity_atnullable string

ISO 8601 timestamp of the most recent recipient-facing activity (view, selection, signing, payment). Powers the "Last Active" sort.

namestring

Display name of the proposal

notesnullable string

Private, admin-only rich-text note attached to the proposal (HTML). Never shown to recipients. Empty/undefined when no note has been added.

proposal_numbernullable string

Tenant-scoped proposal number when set (attrs.proposalNumber).

sent_atnullable string

ISO 8601 timestamp the proposal was sent to the recipient (attrs.timestamps.sent)

settingsobject

Display and behavior settings for the proposal (API format, snake_case)

statusenum

Current workflow status of the proposal

DRAFTSENTPENDINGCANCELLEDON_HOLDWONLOSTEXPIRED

status_detailobject

Status lifecycle details (subset relevant to list views)

tagsarray of string

Tags assigned to this proposal

updated_atstring

ISO 8601 timestamp when the proposal was last updated

updated_bynullable ProposalUser

User who last updated the proposal

paginationobject

Example

{
  "data": [
    {
      "created_at": "example-string",
      "created_by": {
        "email": "example-string",
        "id": "example-string",
        "name": "example-string",
        "avatar_url": "example-string"
      },
      "id": "example-string",
      "name": "example-string",
      "status": "DRAFT",
      "updated_at": "example-string",
      "updated_by": {
        "email": "example-string",
        "id": "example-string",
        "name": "example-string",
        "avatar_url": "example-string"
      },
      "allRecipientsSigned": true,
      "archived": true,
      "archived_at": "example-string",
      "cached_totals": {
        "annually": {
          "max": 100,
          "min": 100
        },
        "currency": "example-string",
        "monthly": {
          "max": 100,
          "min": 100
        },
        "once": {
          "max": 100,
          "min": 100
        },
        "quarterly": {
          "max": 100,
          "min": 100
        },
        "updated_at": "example-string"
      },
      "completed_at": "example-string",
      "crm_linked": {
        "provider": "example-string",
        "recipient_name": "example-string"
      },
      "is_starred": true,
      "is_template": true,
      "last_activity_at": "example-string",
      "notes": "example-string",
      "proposal_number": "example-string",
      "sent_at": "example-string",
      "settings": {
        "avoid_line_item_page_breaks": true,
        "currency": "example-string",
        "disable_proposal_access": true,
        "email_draft": {
          "last_saved": "example-string",
          "message": "example-string",
          "recipients": "example-string",
          "subject": "example-string"
        },
        "expiring_on": "example-string",
        "hide_pdf_download": true,
        "hide_unselected_from_recipient": true,
        "include_modifications_in_line_item_price": true,
        "lock_selections_from_recipient": true,
        "notifications": {
          "override_account_defaults": true,
          "rules": [
            {}
          ]
        },
        "proposal_continuous_scroll": true,
        "recipient": {
          "address": "example-string",
          "contact": {
            "email": "example-string",
            "name": "example-string",
            "phone": "example-string"
          },
          "name": "example-string",
          "website": "example-string"
        },
        "signing": {
          "acceptance_method": "digital_signatures",
          "additional_signers": [
            {}
          ],
          "company_signer": "example-string",
          "custom_company_signer_email": "example-string",
          "custom_company_signer_name": "example-string",
          "is_contact_signer": true,
          "is_multiple_signers": true,
          "override_signature_page_defaults": true,
          "recipient_signer": {
            "email": "example-string",
            "full_name": "example-string"
          },
          "signature_page_agreement_text": "example-string",
          "signature_page_business_label": "example-string",
          "signature_page_client_label": "example-string",
          "signature_page_company_label": "example-string",
          "signature_page_date_label": "example-string",
          "signature_page_labels_captured": true,
          "use_accept": true
        }
      },
      "status_detail": {
        "marked_as_won_method": "manual"
      },
      "tags": [
        "example-string"
      ]
    }
  ]
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals

CreateProposal

Request Body

object

Example

null

Responses

201Proposal created successfully

dataobject

idstring

Unique identifier for the created proposal

Example

{
  "data": {
    "id": "example-string"
  }
}

400Validation error

errorobject

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "example-string",
    "details": {}
  }
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

GET/proposals/{id}

GetProposal

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

200Proposal retrieved successfully

object

Example

null

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

errorobject

Example

{
  "error": {
    "code": "example-string",
    "message": "example-string"
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

PATCH/proposals/{id}

UpdateProposal

Update proposal details such as name, description, or client information

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

object

Example

null

Responses

200Proposal updated successfully

ProposalListItem

allRecipientsSignedboolean

archivedboolean

Whether the proposal is archived

archived_atnullable string

ISO 8601 timestamp when the proposal was archived, or null if not archived

cached_totalsnullable object

Cached pricing totals for quick display

completed_atnullable string

ISO 8601 timestamp all recipient signers completed (attrs.recipientsCompletedAt)

created_atstring

ISO 8601 timestamp when the proposal was created

created_bynullable ProposalUser

User who created the proposal

crm_linkednullable object

CRM link info when proposal is linked to a CRM contact/deal

idstring

Unique identifier for the proposal

is_starredboolean

Whether the current user has starred this proposal

is_templateboolean

Whether this proposal is a reusable template. List templates via GET /api/proposals?is_template=true.

last_activity_atnullable string

ISO 8601 timestamp of the most recent recipient-facing activity (view, selection, signing, payment). Powers the "Last Active" sort.

namestring

Display name of the proposal

notesnullable string

Private, admin-only rich-text note attached to the proposal (HTML). Never shown to recipients. Empty/undefined when no note has been added.

proposal_numbernullable string

Tenant-scoped proposal number when set (attrs.proposalNumber).

sent_atnullable string

ISO 8601 timestamp the proposal was sent to the recipient (attrs.timestamps.sent)

settingsobject

Display and behavior settings for the proposal (API format, snake_case)

statusenum

Current workflow status of the proposal

DRAFTSENTPENDINGCANCELLEDON_HOLDWONLOSTEXPIRED

status_detailobject

Status lifecycle details (subset relevant to list views)

tagsarray of string

Tags assigned to this proposal

updated_atstring

ISO 8601 timestamp when the proposal was last updated

updated_bynullable ProposalUser

User who last updated the proposal

Example

{
  "created_at": "example-string",
  "created_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "id": "example-string",
  "name": "example-string",
  "status": "DRAFT",
  "updated_at": "example-string",
  "updated_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "allRecipientsSigned": true,
  "archived": true,
  "archived_at": "example-string",
  "cached_totals": {
    "annually": {
      "max": 100,
      "min": 100
    },
    "currency": "example-string",
    "monthly": {
      "max": 100,
      "min": 100
    },
    "once": {
      "max": 100,
      "min": 100
    },
    "quarterly": {
      "max": 100,
      "min": 100
    },
    "updated_at": "example-string"
  },
  "completed_at": "example-string",
  "crm_linked": {
    "provider": "example-string",
    "recipient_name": "example-string"
  },
  "is_starred": true,
  "is_template": true,
  "last_activity_at": "example-string",
  "notes": "example-string",
  "proposal_number": "example-string",
  "sent_at": "example-string",
  "settings": {
    "avoid_line_item_page_breaks": true,
    "currency": "example-string",
    "disable_proposal_access": true,
    "email_draft": {
      "last_saved": "example-string",
      "message": "example-string",
      "recipients": "example-string",
      "subject": "example-string"
    },
    "expiring_on": "example-string",
    "hide_pdf_download": true,
    "hide_unselected_from_recipient": true,
    "include_modifications_in_line_item_price": true,
    "lock_selections_from_recipient": true,
    "notifications": {
      "override_account_defaults": true,
      "rules": [
        {
          "emails": [
            "example-string"
          ],
          "event": "proposal_sent",
          "id": "example-string"
        }
      ]
    },
    "proposal_continuous_scroll": true,
    "recipient": {
      "address": "example-string",
      "contact": {
        "email": "example-string",
        "name": "example-string",
        "phone": "example-string"
      },
      "name": "example-string",
      "website": "example-string"
    },
    "signing": {
      "acceptance_method": "digital_signatures",
      "additional_signers": [
        {
          "email": "example-string",
          "full_name": "example-string",
          "id": "example-string",
          "role": "example-string"
        }
      ],
      "company_signer": "example-string",
      "custom_company_signer_email": "example-string",
      "custom_company_signer_name": "example-string",
      "is_contact_signer": true,
      "is_multiple_signers": true,
      "override_signature_page_defaults": true,
      "recipient_signer": {
        "email": "example-string",
        "full_name": "example-string"
      },
      "signature_page_agreement_text": "example-string",
      "signature_page_business_label": "example-string",
      "signature_page_client_label": "example-string",
      "signature_page_company_label": "example-string",
      "signature_page_date_label": "example-string",
      "signature_page_labels_captured": true,
      "use_accept": true
    }
  },
  "status_detail": {
    "marked_as_won_method": "manual"
  },
  "tags": [
    "example-string"
  ]
}

400Validation error

errorobject

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "example-string",
    "details": {}
  }
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

DELETE/proposals/{id}

DeleteProposal

Delete a proposal and all its associated items. The proposal will no longer appear in listings.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

204Proposal deleted successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Not Found - Resource does not exist or access denied

errorobject

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

GET/proposals/{id}/analytics

GetProposalAnalytics

Retrieve analytics events for a specific proposal. Requires authentication and membership in the proposal's organization (or platform admin).

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Query Parameters

end_datestring

Filter events up to this date

event_typeenum

proposal_viewedproposal_sentstatus_changedproposal_signedpdf_viewedsignature_request_sent

Filter by event type

limitinteger

Default: 50. Maximum number of events to return

offsetinteger

Default: 0. Number of events to skip for pagination

start_datestring

Filter events from this date onwards

Responses

200Analytics events retrieved successfully

dataarray of object

event_timestampstring

event_typestring

idstring

metadataobject

userobject

Example

{
  "data": [
    {
      "event_timestamp": "2024-01-20T15:30:00Z",
      "event_type": "example-string",
      "id": "example-string",
      "metadata": {},
      "user": {
        "email": "example-string",
        "full_name": "example-string",
        "public_id": "example-string"
      }
    }
  ]
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/archive

ArchiveProposal

Archive a proposal by setting its archived_at timestamp. Archived proposals are excluded from default listings and become read-only.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

204Proposal archived successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Not authorized to archive this proposal

errorstring

Example

{
  "error": "example-string"
}

404Proposal not found

errorstring

Example

{
  "error": "example-string"
}

409Proposal is already archived

errorstring

Example

{
  "error": "example-string"
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/bulk-archive

BulkArchiveItems

Archive multiple items (line items, groups) from a proposal

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

itemIdsarray of stringrequired

Array of item IDs to archive

Example

{
  "itemIds": [
    "example-string"
  ]
}

Responses

200Items archived successfully

archivedCountinteger

Number of items successfully archived

errorsarray of string

Array of error messages for failed items (only present if some items failed)

messagestring

Success message

Example

{
  "errors": [
    "example-string"
  ],
  "message": "example-string"
}

400Validation error

errorobject

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "example-string",
    "details": {}
  }
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/duplicate

DuplicateProposal

Create a complete copy of an existing proposal with all its groups, items, and pages

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

namestring

Name for the duplicated proposal. Default: "Copy of {original name}"

Example

{
  "name": "example-string"
}

Responses

201Proposal duplicated successfully

dataobject

idstring

ID of the newly created proposal

Example

{
  "data": {
    "id": "example-string"
  }
}

400Validation error

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

GET/proposals/{id}/export

ExportProposalJSON

Path Parameters

idstringrequired

Proposal or template ID

e.g., zw5FD5HGcfE3

Responses

200Importable proposal or template JSON — the same file you get from More → Export as JSON in the app. Ready to import via Create Proposal → Import from JSON.

designobject

Design settings included in the export

idstring

Source proposal or template ID

is_templateboolean

Whether this export is a template

namestring

Proposal or template name

pagesarray of object

Pages, including scope-of-work content, groups, and line items

settingsobject

Proposal settings included in the export

statusstring

Always DRAFT in exports

Example

{
  "name": "example-string",
  "pages": [
    {}
  ],
  "design": {},
  "id": "example-string",
  "is_template": true,
  "settings": {},
  "status": "example-string"
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Insufficient permissions

errorobject

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found or not authorized

errorobject

Example

{
  "error": {
    "code": "example-string",
    "message": "example-string"
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/items

PostProposalsItems

Path Parameters

idstringrequired

Public ID of the proposal.

Request Body

typeenumrequired

The kind of item to create.

line_itemgroupside_by_side

namestringrequired

Display name of the item.

descriptionstring

Optional rich-text/HTML description (stored as the item's content).

priceobject

Required for type=line_item. Pricing definition.

optionalboolean

Whether the item is optional (client can toggle it).

selectedboolean

Whether an optional item is selected by default.

tagsarray of string

Tags to attach to the item.

target_group_idstring

For type=line_item. Group to add into (default first group).

scope_of_work_page_idstring

For type=group or side_by_side. Scope of Work page to add under (default first SOW page).

columnsarray of object

Required for type=side_by_side. The selectable packages/columns. Column ids are generated server-side if omitted.

featuresarray of object

For type=side_by_side comparison style — the feature rows.

selection_typeenum

For type=side_by_side. How many columns a client may select (default loose).

singlemultipleloose

styleenum

For type=side_by_side. Layout style (default standard).

standardcomparison

after_item_idstring

before_item_idstring

Place the new item immediately before this existing item.

order_keynumber

Optional explicit ordering position. Defaults to appending at the end.

Example

{
  "name": "example-string",
  "type": "line_item",
  "after_item_id": "example-string",
  "before_item_id": "example-string",
  "columns": [
    {
      "name": "example-string",
      "description": "example-string",
      "feeType": "fixed",
      "frequency": "example-string",
      "includedFeatures": [
        "example-string"
      ],
      "isSelected": true,
      "price": 100
    }
  ],
  "description": "example-string",
  "features": [
    {
      "name": "example-string",
      "order_key": 100
    }
  ],
  "optional": true,
  "order_key": 100,
  "price": {
    "frequency": "once",
    "model": "fixed",
    "quantity": {
      "current": 100,
      "max": 100,
      "min": 100,
      "unitLabel": "example-string"
    },
    "value": 100
  },
  "scope_of_work_page_id": "example-string",
  "selected": true,
  "selection_type": "single",
  "style": "standard",
  "tags": [
    "example-string"
  ],
  "target_group_id": "example-string"
}

Responses

201Item created.

dataobject

idstring

namestring

order_keynumber

typestring

successboolean

Example

{
  "data": {
    "id": "example-string",
    "name": "example-string",
    "order_key": 100,
    "type": "example-string"
  },
  "success": true
}

400Invalid request (bad type, missing/invalid fields, or no valid parent).

403Not authorized to edit the proposal.

404Proposal (or referenced parent/position item) not found.

POST/proposals/{id}/library-insertions

PostProposalsLibraryInsertions

Path Parameters

idstringrequired

Public ID of the target proposal.

Request Body

typeenumrequired

The kind of library item to insert.

line_itemgrouppageside_by_side

library_item_idstringrequired

Public ID of the library item to copy.

target_group_idstring

For type=line_item only. Public ID of the group in the target proposal to add the line item to. Defaults to the first group in the proposal.

scope_of_work_page_idstring

For type=group or side_by_side. Public ID of the Scope of Work page to insert under. Defaults to the first Scope of Work page.

after_item_idstring

before_item_idstring

Place the new item immediately before this existing item. Same rules as after_item_id. Mutually exclusive with it.

order_keynumber

Optional explicit ordering position. Defaults to appending at the end.

Example

{
  "library_item_id": "example-string",
  "type": "line_item",
  "after_item_id": "example-string",
  "before_item_id": "example-string",
  "order_key": 100,
  "scope_of_work_page_id": "example-string",
  "target_group_id": "example-string"
}

Responses

201Library item inserted into the proposal.

dataobject

idstring

namestring

order_keynumber

typestring

successboolean

Example

{
  "data": {
    "id": "example-string",
    "name": "example-string",
    "order_key": 100,
    "type": "example-string"
  },
  "success": true
}

400Invalid request (missing/invalid type or required target).

403Not authorized to edit the target proposal.

404Proposal or library item not found (or not in the same organization).

POST/proposals/{id}/pdf

GenerateProposalPDF

Generate a PDF document for the specified proposal. Returns the PDF as a binary download.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Request Body

No properties

Example

{}

Responses

200PDF generated successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Proposal not found

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/star

StarProposal

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.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

200Proposal starred successfully

is_starredboolean

Example

{
  "is_starred": true
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Not Found - Resource does not exist or access denied

errorobject

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/unarchive

UnarchiveProposal

Unarchive a proposal by clearing its archived_at timestamp. The proposal will return to active status and become editable again.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

204Proposal unarchived successfully

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

403Not authorized to unarchive this proposal

errorstring

Example

{
  "error": "example-string"
}

404Proposal not found

errorstring

Example

{
  "error": "example-string"
}

409Proposal is not archived

errorstring

Example

{
  "error": "example-string"
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

POST/proposals/{id}/unstar

UnstarProposal

Remove the star from a proposal for the current user. This operation is idempotent - unstarring a proposal that is not starred has no effect.

Path Parameters

idstringrequired

Proposal ID

e.g., zw5FD5HGcfE3

Responses

200Proposal unstarred successfully

is_starredboolean

Example

{
  "is_starred": true
}

401Authentication required

errorobject

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "example-string",
    "details": {}
  }
}

404Not Found - Resource does not exist or access denied

errorobject

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "example-string",
    "details": {}
  }
}

500Internal server error

errorobject

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "example-string",
    "details": {}
  }
}

Schemas

Item Types

ProposalListItem7 required

Used by: ListProposals (response 200)·UpdateProposal (response 200)

Summary of a proposal for use in list views

idstringrequired

Unique identifier for the proposal

statusenumrequired

Current workflow status of the proposal

DRAFTSENTPENDINGCANCELLEDON_HOLDWONLOSTEXPIRED

namestringrequired

Display name of the proposal

created_bynullable ProposalUserrequired

User who created the proposal

updated_bynullable ProposalUserrequired

User who last updated the proposal

created_atstringrequired

ISO 8601 timestamp when the proposal was created

updated_atstringrequired

ISO 8601 timestamp when the proposal was last updated

archivedboolean

Whether the proposal is archived

archived_atnullable string

ISO 8601 timestamp when the proposal was archived, or null if not archived

settingsobject

Display and behavior settings for the proposal (API format, snake_case)

is_templateboolean

Whether this proposal is a reusable template. List templates via GET /api/proposals?is_template=true.

is_starredboolean

Whether the current user has starred this proposal

cached_totalsnullable object

Cached pricing totals for quick display

status_detailobject

Status lifecycle details (subset relevant to list views)

allRecipientsSignedboolean

sent_atnullable string

ISO 8601 timestamp the proposal was sent to the recipient (attrs.timestamps.sent)

completed_atnullable string

ISO 8601 timestamp all recipient signers completed (attrs.recipientsCompletedAt)

last_activity_atnullable string

ISO 8601 timestamp of the most recent recipient-facing activity (view, selection, signing, payment). Powers the "Last Active" sort.

crm_linkednullable object

CRM link info when proposal is linked to a CRM contact/deal

tagsarray of string

Tags assigned to this proposal

notesnullable string

Private, admin-only rich-text note attached to the proposal (HTML). Never shown to recipients. Empty/undefined when no note has been added.

proposal_numbernullable string

Tenant-scoped proposal number when set (attrs.proposalNumber).

Example

{
  "created_at": "example-string",
  "created_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "id": "example-string",
  "name": "example-string",
  "status": "DRAFT",
  "updated_at": "example-string",
  "updated_by": {
    "email": "example-string",
    "id": "example-string",
    "name": "example-string",
    "avatar_url": "example-string"
  },
  "allRecipientsSigned": true,
  "archived": true,
  "archived_at": "example-string",
  "cached_totals": {
    "annually": {
      "max": 100,
      "min": 100
    },
    "currency": "example-string",
    "monthly": {
      "max": 100,
      "min": 100
    },
    "once": {
      "max": 100,
      "min": 100
    },
    "quarterly": {
      "max": 100,
      "min": 100
    },
    "updated_at": "example-string"
  },
  "completed_at": "example-string",
  "crm_linked": {
    "provider": "example-string",
    "recipient_name": "example-string"
  },
  "is_starred": true,
  "is_template": true,
  "last_activity_at": "example-string",
  "notes": "example-string",
  "proposal_number": "example-string",
  "sent_at": "example-string",
  "settings": {
    "avoid_line_item_page_breaks": true,
    "currency": "example-string",
    "disable_proposal_access": true,
    "email_draft": {
      "last_saved": "example-string",
      "message": "example-string",
      "recipients": "example-string",
      "subject": "example-string"
    },
    "expiring_on": "example-string",
    "hide_pdf_download": true,
    "hide_unselected_from_recipient": true,
    "include_modifications_in_line_item_price": true,
    "lock_selections_from_recipient": true,
    "notifications": {
      "override_account_defaults": true,
      "rules": [
        {
          "emails": [
            "example-string"
          ],
          "event": "proposal_sent",
          "id": "example-string"
        }
      ]
    },
    "proposal_continuous_scroll": true,
    "recipient": {
      "address": "example-string",
      "contact": {
        "email": "example-string",
        "name": "example-string",
        "phone": "example-string"
      },
      "name": "example-string",
      "website": "example-string"
    },
    "signing": {
      "acceptance_method": "digital_signatures",
      "additional_signers": [
        {
          "email": "example-string",
          "full_name": "example-string",
          "id": "example-string",
          "role": "example-string"
        }
      ],
      "company_signer": "example-string",
      "custom_company_signer_email": "example-string",
      "custom_company_signer_name": "example-string",
      "is_contact_signer": true,
      "is_multiple_signers": true,
      "override_signature_page_defaults": true,
      "recipient_signer": {
        "email": "example-string",
        "full_name": "example-string"
      },
      "signature_page_agreement_text": "example-string",
      "signature_page_business_label": "example-string",
      "signature_page_client_label": "example-string",
      "signature_page_company_label": "example-string",
      "signature_page_date_label": "example-string",
      "signature_page_labels_captured": true,
      "use_accept": true
    }
  },
  "status_detail": {
    "marked_as_won_method": "manual"
  },
  "tags": [
    "example-string"
  ]
}

Other

ProposalCachedTotalRange2 required

A price range with minimum and maximum values

minnumberrequired

Minimum total amount

maxnumberrequired

Maximum total amount

Example

{
  "max": 100,
  "min": 100
}

ProposalUser3 required

Used by: ProposalListItem.created_by.anyOf[0]·ProposalListItem.updated_by.anyOf[0]

User profile embedded in proposal responses (used for both created_by and updated_by)

idstringrequired

Public user ID

namestringrequired

Full name

emailstringrequired

Email address

avatar_urlnullable string

Avatar image URL

Example

{
  "email": "example-string",
  "id": "example-string",
  "name": "example-string",
  "avatar_url": "example-string"
}