Sign inStart free trial

← All action domains

Proposals

16 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Proposal activity

proposals.activityread

The trail of what happened to a proposal and when — created, sent, first opened by the customer, accepted or declined. This answers the question every contractor asks before following up: have they even looked at it yet? Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredId of the proposal.
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.activity \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_activity at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete proposal

proposals.deletewriteconfirm

Permanently delete a proposal and its activity trail. The customer-facing link stops working immediately, so anyone still holding it sees a not-found page. An accepted proposal is the record of what somebody agreed to buy and cannot be deleted. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredId of the proposal to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.delete \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_delete at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete financing product

proposals.delete_financingwriteconfirm

Permanently remove one financing product. Proposals that already offered it keep their saved terms — a proposal's financing choice is a copy, not a reference — so this only stops the product from being offered on future proposals. Prefer setting is_active to false if you may want it back. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredId of the financing product to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.delete_financing \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_delete_financing at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete price book item

proposals.delete_price_book_itemwriteconfirm

Permanently remove one item from the price book. Proposals that already used it keep their lines — a proposal's lines are copies, not references — so this affects only what appears in the builder's pickers from now on. Prefer setting is_active to false if you may want it back. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredId of the price book item to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.delete_price_book_item \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_delete_price_book_item at https://app.chirply.io/api/mcp, same bearer token, same input.

Draft with AI

proposals.draft_with_aiwrite

Describe a job in plain language and get back a priced Good/Better/Best draft, grounded in this account's own price book. The AI asks a clarifying question instead of guessing whenever a quantity that drives the price is missing — footage, fixture count, storeys — so a reply may be a question rather than a draft. Nothing is saved or sent: the returned draft is a suggestion to review, edit and then save with proposals.save. Uses this account's own OpenRouter key and is billed to it. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
messagesobject[]requiredThe drafting conversation so far, oldest first. For a first request this is a single user turn describing the job.
messages[].role"user" | "assistant"requiredWho said this turn.
messages[].contentstringrequiredWhat was said.
proposal_idstring (uuid)optionalAn existing proposal to revise. Its current options are given to the AI so a request like 'drop the premium fixtures' modifies what's there.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.draft_with_ai \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "example"
      }
    ]
  }'
Test with your API key

Over MCP the same operation is the tool proposals_draft_with_ai at https://app.chirply.io/api/mcp, same bearer token, same input.

Open proposal

proposals.getread

Fetch one proposal in full — every option with all its lines and add-ons, the attachments, the customer-facing link, and the activity trail showing when it was sent, opened, and decided. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredId of the proposal to open.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.get \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_get at https://app.chirply.io/api/mcp, same bearer token, same input.

Proposal settings

proposals.get_settingsread

The account's proposal defaults: sales-tax rate applied to new options, how many days a proposal stays valid, the terms shown under the total, the wording above the accept button, and whether accepting creates an invoice automatically. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.get_settings \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool proposals_get_settings at https://app.chirply.io/api/mcp, same bearer token, same input.

Proposals

proposals.listread

List proposals with their status, customer and price. Each returns a `from` price — the cheapest option — because a proposal offers several, and its accepted total once the customer has chosen. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
status"draft" | "sent" | "viewed" | "accepted" | "declined" | "expired"optionalOnly return proposals in this state.
contact_idstring (uuid)optionalOnly return proposals for this contact.
querystringoptionalText to match in the title or scope of work.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.list \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool proposals_list at https://app.chirply.io/api/mcp, same bearer token, same input.

Financing products

proposals.list_financingread

List the financing products this account offers, with their APR, term and qualifying amount range. This app only DISPLAYS the monthly payment on a proposal — it does not originate, underwrite or service any loan; the lender's own approval happens off-platform. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
include_inactivebooleanoptionalAlso return products that have been switched off. Default: false
qualifying_amount_centsintegeroptionalIf given, return only products a proposal of this amount (integer cents) qualifies for, each annotated with its monthly payment.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.list_financing \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool proposals_list_financing at https://app.chirply.io/api/mcp, same bearer token, same input.

Price book

proposals.list_price_bookread

List the account's reusable services and materials with their unit prices — the catalog the proposal builder's pickers draw from and the AI drafter is grounded in. Prices are returned in integer cents. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
kind"service" | "material" | "line"optionalOnly return items of this kind.
categorystringoptionalOnly return items in this category.
include_inactivebooleanoptionalAlso return retired items, which are hidden from the builder's pickers. Default: false
querystringoptionalText to match in the item's name or description.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.list_price_book \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool proposals_list_price_book at https://app.chirply.io/api/mcp, same bearer token, same input.

Record decision

proposals.record_decisionwriteconfirm

Record that the customer accepted or declined, for the times they tell you over the phone or in person instead of clicking the link. Accepting freezes the chosen option and its add-ons at today's prices, exactly as the customer-facing page does. Only use this for a decision a real customer actually gave you. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredId of the proposal being decided.
decision"accepted" | "declined"requiredWhat the customer said.
option_idstringoptionalWhich option they chose. Required when accepting.
addon_idsstring[]optionalIds of the add-on lines they also wanted. Ids not on the chosen option are ignored. Default: []
accepted_namestringoptionalWho gave the go-ahead, recorded in place of a typed signature.
reasonstringoptionalWhy they declined, if they said. Kept internally for reporting.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.record_decision \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "decision": "accepted"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_record_decision at https://app.chirply.io/api/mcp, same bearer token, same input.

Save proposal

proposals.savewrite

Create or update a proposal and its options. Pass an id to update an existing one, omit it to create a draft. Every option total is recalculated from its lines here — subtotal minus discount plus surcharge, then tax — so a total you send is ignored. This only writes the document; it does not notify the customer (use proposals.send). Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
idstring (uuid)optionalId of the proposal to update. Omit to create a draft.
contact_idstring (uuid)optionalThe customer this proposal is for. Required before it can be sent.
titlestringoptionalInternal title, e.g. 'Front elevation + walkway — 12 Oak St'.
job_summarystringoptionalCustomer-facing scope of work, as PLAIN TEXT — HTML and markdown are not rendered, they are shown literally. Line breaks are preserved. Put no prices here; the options carry the numbers.
category"Installation" | "Repair" | "Replacement" | "Maintenance plan" | "Seasonal / event" | "Commercial" | … 2 moreoptionalThe kind of work this proposal covers. Used for filtering and reporting.
price_display"itemized" | "total"optionalWhether the customer sees every line and its price ('itemized'), or only each option's final number ('total').
notesstringoptionalInternal notes. Never shown to the customer on the proposal page.
optionsobject[]optionalThe complete set of options, replacing whatever is stored. Send every option and every line in its final state — this is not a patch. Three is the maximum the customer-facing page compares side by side.
options[].namestringrequiredThe option's name as the customer sees it, e.g. 'Good', 'Better', 'Premium'.
options[].descriptionstringoptionalA sentence explaining what makes this option different from the others.
options[].itemsobject[]requiredThe base lines, always billed if the customer chooses this option.
options[].items[].kind"service" | "material" | "line"optionalWhat this line represents: 'service' for labour, 'material' for parts and fixtures, 'line' for anything else (fees, allowances, trip charges). Default: "line"
options[].items[].descriptionstringrequiredWhat the customer sees on this line, e.g. 'Install 140 ft of gutter guard'.
options[].items[].quantitynumberoptionalHow many units. May be fractional for hours or measured footage (e.g. 2.5). Default: 1
options[].items[].unitPriceCentsintegerrequiredPrice per unit in INTEGER CENTS — 24950 means $249.50. Never dollars.
options[].addonsobject[]optionalOpt-in upgrades the customer ticks themselves on the proposal page. These are NOT included in the option's headline total; they are added only if selected. Default: []
options[].addons[].kind"service" | "material" | "line"optionalWhat this line represents: 'service' for labour, 'material' for parts and fixtures, 'line' for anything else (fees, allowances, trip charges). Default: "line"
options[].addons[].descriptionstringrequiredWhat the customer sees on this line, e.g. 'Install 140 ft of gutter guard'.
options[].addons[].quantitynumberoptionalHow many units. May be fractional for hours or measured footage (e.g. 2.5). Default: 1
options[].addons[].unitPriceCentsintegerrequiredPrice per unit in INTEGER CENTS — 24950 means $249.50. Never dollars.
options[].discountCentsintegeroptionalFlat money off in INTEGER CENTS, applied before tax. Default: 0
options[].surchargeCentsintegeroptionalFlat money on in INTEGER CENTS (permit, trip charge, difficult access), applied before tax. Default: 0
options[].taxRatenumberoptionalSales tax as a PERCENT, e.g. 8.25 for 8.25%. Not a fraction, not a multiplier. Default: 0
options[].financingIdsarray of (string (uuid))optionalUp to 3 financing product ids (from proposals.list_financing) to offer on this option. Products the total doesn't qualify for are hidden from the customer automatically. Default: []
filesobject[]optionalCustomer-facing attachments. Project Preview pairs remain interactive in the public proposal.
files[].namestringrequiredAttachment label shown to the customer.
files[].urlstring (uri)requiredPermanent public URL for the attachment or rendered after image.
files[].typestringrequiredMIME type of the attachment, e.g. image/png. For an interactive before/after comparison use application/x-project-preview (or set kind to project_preview); the preview type used before September 2026 is still accepted.
files[].kind"attachment" | "project_preview"optionalUse project_preview to render a draggable before/after inside the proposal.
files[].beforeUrlstring (uri)optionalOriginal project photo URL. Required for project_preview.
files[].afterUrlstring (uri)optionalGenerated result URL. Required for project_preview.
files[].previewIdstring (uuid)optionalProject Preview archive row linked to this attachment.
files[].previewSessionIdstringoptionalProject Preview session grouping related angles or styles.
files[].designstringoptionalHuman-readable transformation shown with the comparison.
valid_untilstringoptionalLast day the customer may accept. After it, the page refuses acceptance and says so.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.save \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "contact_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_save at https://app.chirply.io/api/mcp, same bearer token, same input.

Save financing product

proposals.save_financingwrite

Create or update a financing product customers can be offered on a proposal. The monthly payment this app shows is a standard amortized calculation from the APR and term you set here — set them to match what your lender actually approves, because the number a customer sees on the proposal is the number they will expect. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
idstring (uuid)optionalId of the product to update. Omit to create a new one.
namestringrequiredWhat the customer sees, e.g. '12 months, no interest'.
lenderstringoptionalThe finance company behind it, shown as 'via …'.
aprnumberoptionalAnnual percentage rate as a PERCENT, e.g. 9.99. Use 0 for a promotional 0% offer. Default: 0
term_monthsintegerrequiredHow many monthly payments the customer makes.
min_amount_centsintegeroptionalSmallest proposal total this product may be offered on, in INTEGER CENTS. Default: 0
max_amount_centsinteger (or null)optionalLargest proposal total it may be offered on, in INTEGER CENTS. Null means no ceiling. Default: null
is_activebooleanoptionalSet false to stop offering this product. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.save_financing \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "term_months": 1
  }'
Test with your API key

Over MCP the same operation is the tool proposals_save_financing at https://app.chirply.io/api/mcp, same bearer token, same input.

Save price book item

proposals.save_price_book_itemwrite

Create or update one reusable service or material in the price book. Pass an id to update an existing item, omit it to create a new one. Item names are unique within the account, so saving under an existing name is rejected rather than silently creating a duplicate the builder's picker would show twice. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
idstring (uuid)optionalId of the item to update. Omit to create a new one.
kind"service" | "material" | "line"optionalWhat this line represents: 'service' for labour, 'material' for parts and fixtures, 'line' for anything else (fees, allowances, trip charges). Default: "service"
namestringrequiredWhat this is called in the picker, e.g. 'Standard fixture install'.
descriptionstringoptionalOptional detail shown under the name, and given to the AI drafter.
unit_price_centsintegerrequiredPrice per unit in INTEGER CENTS — 12500 means $125.00.
unitstringoptionalWhat one unit is: 'each', 'hour', 'linear ft', 'sq ft', 'zone', 'trip'. Default: "each"
categorystringoptionalGrouping shown in the picker, e.g. 'Labour', 'Fixtures', 'Controls'.
is_activebooleanoptionalSet false to retire an item without deleting the proposals that used it. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.save_price_book_item \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "unit_price_cents": 1
  }'
Test with your API key

Over MCP the same operation is the tool proposals_save_price_book_item at https://app.chirply.io/api/mcp, same bearer token, same input.

Save proposal settings

proposals.save_settingswriteadmin only

Update the account's proposal defaults. Changing the default tax rate affects new options only — proposals already built keep the rate they were priced at, so an already-sent quote never changes underneath the customer looking at it. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

FieldTypeRequiredDescription
default_tax_ratenumberoptionalSales tax as a PERCENT applied to new options, e.g. 8.25.
default_valid_daysintegeroptionalHow many days a new proposal stays acceptable for.
termsstring (or null)optionalTerms shown under the total on the customer-facing page — deposit, warranty, scheduling.
accept_disclaimerstring (or null)optionalThe line above the signature box, e.g. 'By typing your name you accept this proposal.'
auto_invoicebooleanoptionalWhen true, accepting a proposal immediately creates a draft invoice from the chosen option's real line items. Leave false to review the accepted scope before billing.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.save_settings \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "default_tax_rate": 1,
    "default_valid_days": 1
  }'
Test with your API key

Over MCP the same operation is the tool proposals_save_settings at https://app.chirply.io/api/mcp, same bearer token, same input.

Send proposal

proposals.sendwriteconfirm

Mark a proposal as sent and return the customer-facing link. Sending is what makes the link acceptable — until then it renders as a preview the customer cannot act on. This does not itself deliver an email or text; pass the returned url to communications.send_email or communications.send_sms, or copy it to the customer yourself. Requires the AI Quotes & Proposals app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredId of the proposal to mark as sent.

Example

curl -X POST https://app.chirply.io/api/v1/actions/proposals.send \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool proposals_send at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=proposals — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.