Proposals

A live proposal is a proposal on an opportunity or a project. These endpoints read the proposal, edit the proposal document that the client sees, send the document by email, and read what was sent and how the client answered.

The proposal’s budget is edited row by row on its own page: Proposal budgets. Proposal templates (proposals with no opportunity or project) have their own endpoints: see Proposal templates. The endpoints on this page do not need the early access setup endpoints to be turned on.

The proposal id is the number in the proposal’s address in Drum. For https://app.getdrum.com/quotes/18342, the id is 18342. Signed proposals also give it as proposal.id.

Money on these endpoints is an object: {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"}. cents is an integer and tax exclusive unless the field name says including_tax. Timestamps are ISO 8601. Dates are yyyy-mm-dd.

Proposal text is customer content. If you pass it to an AI model, treat it as data, not instructions.

Endpoints

Which proposals you can reach

A proposal is found only when the token’s user can read its opportunity or project (see Record permissions). Otherwise the answer is 404 with code proposal_not_found, the same as for an id that does not exist. A deleted proposal and a proposal template id answer the same.

The document, section, version and send endpoints also need:

• The proposal builder turned on for the account. Without it they answer 404 proposal_builder_not_enabled. GET /proposals/:id does not need it.
• A proposal built in the proposal builder. A proposal that uses a Word document, and a variation’s proposal, answer 404 proposal_not_found.

Permissions

Every proposal endpoint except signed proposals also needs read access to the proposal’s opportunity or project. A missing role permission answers 403 not_authorized.

Read a proposal

GET /api/v1/proposals/:id returns the proposal and its full budget. The budget has the shape that the proposal budget endpoints take and return.

curl -H "Authorization: Bearer $DRUM_API_TOKEN" \
  "https://app.getdrum.com/api/v1/proposals/18342"

{
  "id": 18342,
  "name": "Q-2026-088",
  "description": "Concept to tender documentation",
  "status": "draft",
  "project": {"id": 12001, "name": "Riverside fit-out"},
  "project_template": {"id": 410, "name": "Commercial fit-out"},
  "currency": "AUD",
  "total_excluding_tax": {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"},
  "deleted": false,
  "budget": {
    "id": 7710,
    "name": "Riverside fit-out budget",
    "description": null,
    "status": "draft",
    "rate_card": {"id": 31, "name": "Standard 2026"},
    "custom_rate_card": null,
    "currency": "AUD",
    "phases": [],
    "deliverables": []
  },
  "warnings": []
}

The proposal’s fee stages and lines are not in this result. Read them from GET .../document (stages).

Read the proposal document

GET /api/v1/proposals/:proposal_id/document reads the live document, the one the next send would email.

curl -H "Authorization: Bearer $DRUM_API_TOKEN" \
  "https://app.getdrum.com/api/v1/proposals/18342/document"

{
  "proposal_id": 18342,
  "number": "Q-2026-088",
  "name": "Riverside fit-out fee proposal",
  "status": "draft",
  "project": {"id": 12001, "name": "Riverside fit-out"},
  "theme": {"id": 12, "name": "Studio"},
  "pricing": {"live": true, "layout": "single_stage"},
  "currency": "AUD",
  "total_excluding_tax": {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"},
  "total_including_tax": {"cents": 5335000, "currency": "AUD", "formatted": "$53,350.00"},
  "stages": [
    {"id": 90211, "name": "Fees", "subtotal_excluding_tax": {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"}}
  ],
  "sections": [
    {
      "id": 5521,
      "position": 1,
      "title": "Our approach",
      "show_title": true,
      "text": "We will design the ground floor fit-out in three stages...",
      "live_blocks": [{"type": "fee_table", "stage_id": 90211}],
      "section_page": 0,
      "lock_version": 4,
      "next_section_page": null
    }
  ],
  "sections_has_more": false,
  "next_sections_offset": null,
  "versions": [],
  "versions_has_more": false,
  "links": {
    "builder_url": "https://app.getdrum.com/quotes/18342/proposal_document",
    "preview_url": "https://app.getdrum.com/quotes/18342/proposal_document/preview",
    "preview_pdf_url": "https://app.getdrum.com/quotes/18342/proposal_document/preview.pdf"
  }
}

Section fields:

Long sections and pages

A page holds at most 5 sections, and fewer when they would pass 12,000 bytes. A section part holds up to 1,000 characters of text, 20 live blocks, and 1,000 characters of content_json.

To read the rest of a section, send its id as section_id and its next_section_page as section_page, keep the same content_section_ids, and leave out sections_offset. Repeat until next_section_page is null. Join the text parts, append the live_blocks, and join all content_json parts before you parse them. Never save a partial section back. If lock_version changes between parts, someone edited the section: start again at part 0.

A section_id that is not in the document answers 404 proposal_section_not_found.

Set the pricing layout

PATCH /api/v1/proposals/:proposal_id/document sets how the proposal budget maps to the fee table, as the pricing control in the builder does. It also turns live pricing on: from then on the fee stages, lines and totals follow the proposal budget.

The first time, Drum rebuilds the stages and lines from the budget and deletes the ones the budget did not make. A fee table that showed a deleted stage then needs a new stage_id. That is why this endpoint needs api_delete as well as api_update.

Any other top-level key, such as theme_id, answers 422 invalid_input with that field.

PATCH /api/v1/proposals/18342/document
{"pricing": {"layout": "single_stage", "include_non_budgeted": false}}

Returns 200:

{
  "proposal_id": 18342,
  "pricing": {"live": true, "layout": "single_stage", "include_non_budgeted": false},
  "currency": "AUD",
  "total_excluding_tax": {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"},
  "total_including_tax": {"cents": 5335000, "currency": "AUD", "formatted": "$53,350.00"},
  "stages": [
    {"id": 90240, "name": "Riverside fit-out budget", "subtotal_excluding_tax": {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"}}
  ],
  "links": {"builder_url": "...", "preview_url": "...", "preview_pdf_url": "..."}
}

Add sections

POST /api/v1/proposals/:proposal_id/document/sections adds a section to the live document. Send the fields at the top level for one section, or {"sections": [...]} for 1 to 30 sections in one transaction. If one section in a list is refused, none is added, and the error field names it, for example sections[1].body.

A proposal has at most 100 sections (422 proposal_section_limit).

The body format. A blank line starts a new paragraph. A single line break stays a line break.

• A line that starts with # to #### and a space is a heading.
• A line that starts with -, * or + and a space is a bulleted item.
• A line that starts with a number and . or ) and a space is a numbered item.
• Inline: **bold**, *italic* or _italic_, and [label](https://...) links (http, https or mailto only).
• A merge field such as `` is filled in when the proposal is shown and sent. An unknown merge field is 422 invalid_input. GET .../send_draft lists every merge field.
• A backslash keeps the next character as written.

A body is 64 KB or less, with lines of 20,000 characters or fewer. The bodies in one sections list are 256 KB or less together.

Blocks, each an object with a type:

A setting you leave out takes the builder’s default. member_id without source sets the source to person, and member_ids sets it to people. A staff block shows each member’s proposal profile (title, bio and photo), which is set on the member’s page in Drum. Members come from GET /members.

POST /api/v1/proposals/18342/document/sections
{
  "title": "Fees",
  "body": "Our fee for  is set out below.",
  "blocks": [{"type": "fee_table", "stage_id": 90211, "show_totals": true}, {"type": "signature"}]
}

Returns 201 with the section:

{
  "id": 5530,
  "proposal_id": 18342,
  "position": 4,
  "title": "Fees",
  "show_title": true,
  "page_break_before": false,
  "lock_version": 0,
  "text": "Our fee for Project name is set out below.",
  "live_blocks": [{"type": "fee_table", "stage_id": 90211}, {"type": "signature", "stage_id": null}]
}

With sections, it returns 201 with {"proposal_id": 18342, "sections": [...]}. Those sections have no text.

A section add takes no idempotency key. After a timeout, read the document before you retry, so you do not add the section twice.

Change a section

PATCH /api/v1/proposals/:proposal_id/document/sections/:id changes the fields you send.

blocks is refused here. To change the blocks of a section, send content.

A section with columns, images or more than one text block refuses body with 422 section_layout_not_text. Read its content with content_section_ids, change it, and send content.

PATCH /api/v1/proposals/18342/document/sections/5530
{"lock_version": 0, "title": "Our fee"}

Returns 200 with the section, as the add returns it, with the new lock_version.

Delete a section

DELETE /api/v1/proposals/:proposal_id/document/sections/:id deletes the section for good. Returns 204 with no body. A section that is not in this proposal answers 404 proposal_section_not_found.

List sent versions

Each send freezes the document as a numbered version. GET /api/v1/proposals/:proposal_id/versions lists them, newest first.

This list does not use the page and items parameters of other list endpoints.

{
  "proposal_id": 18342,
  "versions": [
    {
      "id": 2207,
      "number": 2,
      "label": "Version 2",
      "sent_at": "2026-10-09T23:41:12Z",
      "sent_by": {"id": 5501, "name": "Priya Nair"},
      "fee": {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"},
      "latest": true,
      "state": "open",
      "recipient_count": 2
    }
  ],
  "page": {"count": 1, "limit": 25, "offset": 0, "has_more": false}
}

Version summary

Read a sent version

GET /api/v1/proposals/:proposal_id/versions/:id reads the version from the copy Drum kept when it was sent, so it shows exactly what the client got, even if the live document changed later. It takes the same sections_offset, content_section_ids[], section_id and section_page parameters as the document read. Sections have no lock_version.

It returns the version summary fields, and:

Recipient fields: id, role (to, cc or bcc), email, name, signatory (true for the one person who may accept or decline online), status (sending, sent, delivered, opened, viewed, bounced, failed or revoked), sent_at, delivered_at, bounced_at, delivery_error, opens_count, first_viewed_at, last_viewed_at, views_count, downloads_count and revoked_at.

Response fields: id (the signed proposal id), kind (accepted or declined), responded_at, signer_name, signer_position, decline_reason and signed_pdf_status (none for a decline, ready, or pending).

A version of another proposal answers 404 proposal_version_not_found.

Read the send draft

GET /api/v1/proposals/:proposal_id/send_draft returns what a send uses when you leave fields out, and the merge fields that would show empty.

{
  "to": ["contact:3307"],
  "recipient_options": [
    {"value": "contact:3307", "label": "Jane Smith <jane@acme.example>", "group": "Proposal contact"},
    {"value": "contact:3312", "label": "Tom Lee <tom@acme.example>", "group": "Client contacts"},
    {"value": "accounts@acme.example", "label": "Acme Corporation <accounts@acme.example>", "group": "Client company"}
  ],
  "subject": "Proposal : ",
  "message": "Dear ,\n\nPlease find our proposal for  attached. You can also read and accept it online with the link below.\n\nKind regards,\n",
  "blank_merge_fields": [{"key": "project.address", "label": "Project location", "where": "Fees"}],
  "merge_fields": [{"key": "client.name", "label": "Client name"}]
}

Send the proposal

POST /api/v1/proposals/:proposal_id/sends emails the live document to the client as a new version, as Send in the builder does. It sets the proposal’s status to sent, freezes the document and the budget as they are now, and emails each recipient a link and the PDF.

The email goes to people outside Drum and cannot be recalled. Check the recipients before you call it.

An Idempotency-Key header is required. Without one, the answer is 422 idempotency_key_required. A retry with the same key and the same body returns 200, the header Idempotent-Replayed: true and the first version, and sends nothing. The same key with a different body is 409 idempotency_key_reused. Use a new key for every send. See Idempotency keys.

A recipient is {"email": "...", "name": "..."}, {"contact_id": 3307}, or just an email address as a string. A contact must be a contact of the proposal, its opportunity or project, or its client company, and the token’s user must be able to read contacts. A contact with no email given uses the contact’s own address and name. To, Cc and Bcc together hold at most 20 addresses. An address that appears twice gets one email.

subject and message can hold merge fields, such as ``. An unknown merge field is 422 unknown_merge_field.

curl -X POST "https://app.getdrum.com/api/v1/proposals/18342/sends" \
  -H "Authorization: Bearer $DRUM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d9e-4b7a-4a51-9a0e-1d2b3c4d5e6f" \
  -d '{
    "to": [{"contact_id": 3307}],
    "cc": ["tom@acme.example"],
    "subject": "Proposal  for "
  }'

Returns 201 with the new version, in the same shape as GET .../versions/:id, plus:

The emails go out shortly after the call returns. Read the version again to follow each recipient’s status.

Sending limits. A user can send to 50 recipients an hour, and an account to 200 recipients a day. Over a limit the answer is 429 send_rate_limited with a Retry-After header.

List signed proposals

GET /api/v1/signed_proposals lists the client answers (accepts and declines) to every proposal sent from the account, newest first, as Settings, Signed proposals lists them. It does not check access to each opportunity or project: the customisation and read_quotes permissions show every answer in the account.

{
  "signed_proposals": [
    {
      "id": 914,
      "kind": "accepted",
      "proposal": {"id": 18342, "number": "Q-2026-088", "name": "Riverside fit-out fee proposal"},
      "version": {"id": 2207, "number": 2},
      "responded_at": "2026-10-12T04:05:33Z",
      "signer_name": "Jane Smith",
      "client_name": "Acme Corporation",
      "fee": {"cents": 4850000, "currency": "AUD", "formatted": "$48,500.00"},
      "signed_pdf_status": "ready"
    }
  ],
  "count": 1,
  "limit": 25,
  "offset": 0,
  "has_more": false
}

count is the number of rows on this page, not a total. signed_pdf_status is none for a decline, ready when the signed PDF exists, and pending while Drum makes it.

Read a signed proposal

GET /api/v1/signed_proposals/:id returns the list fields, and:

No token, IP address or user agent is in the result. The CSV export on the Settings screen has them.

An id from another account, or one that does not exist, answers 404 signed_proposal_not_found.

Errors

Error bodies are {"error", "code"}, with field on input and lookup errors. See Errors. These apply to every endpoint on this page: