Skip to main content
POST
https://api.proposales.com
/
v3
/
proposals
Create Proposal
curl --request POST \
  --url https://api.proposales.com/v3/proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "company_id": 123,
  "language": "<string>",
  "creator_email": "<string>",
  "contact_email": "<string>",
  "background_image": {},
  "background_video": {},
  "title_md": "<string>",
  "description_md": "<string>",
  "recipient": {},
  "data": {},
  "invoicing_enabled": true,
  "tax_options": {},
  "blocks": [
    {}
  ],
  "attachments": [
    {}
  ]
}
'
{
  "proposal": {
    "uuid": "<string>",
    "url": "<string>"
  }
}

​
Body

​
company_id
number
required
The ID of the Proposales company that the proposal draft should belong to.
​
language
string
required
A two-letter ISO 3166-1 alpha-2 language code indicating the language of the proposal.
​
creator_email
string
Email address of the user who should be set as the creator of this proposal.The user must:
  • Have an account in the system
  • Be a member of the same company specified in company_id
  • Not be disabled
If not provided or if the email is not found, the API token owner will be used as the creator. This field is useful when multiple users share the same API token and you want proposals to be created under their individual names instead of the API token owner’s name.Example use case: A team of 10 sales people share the same API token via a third-party integration. By passing creator_email, each salesperson can create proposals that appear under their own name, maintaining proper attribution and audit trails.
​
contact_email
string
Email address of the user who should be set as the contact person for this proposal.The user must:
  • Have an account in the system
  • Be a member of the same company specified in company_id
  • Not be disabled
If the email is not found or doesn’t have access to the company, the creator will be used as the contact person by default.Note: The contact person is the internal team member (salesperson/account manager) who will receive notifications and appear as the point of contact for the proposal. This is different from recipient which is the external customer receiving the proposal.
​
background_image
object
Background image id and uuid. Can be fetched from a template.
​
background_video
object
Background video id and uuid. Can be fetched from a template.
​
title_md
string
The proposal title as Markdown. Only data URLs for variables are supported, other formatting syntax is ignored.
​
description_md
string
The proposal description as Markdown. We support # for headers, * for bold, a < prefix for left-aligned paragraphs and data URLs for variables (see example).
​
recipient
object
The recipient of the proposal. Can either be a new recipient, or existing one.Needs to be this shape:
{ id: number } |
{
  first_name?: string;
  last_name?: string;
  email?: string;
  phone?: string;
  company_name?: string;
  sources?: {
    integration?: {
      // Integration ID
      id: number;
      // Unique identifier for the integration contact
      contactId: string;
      // Optional integration metadata
      metadata: Record<string, unknown>;
    }
  }
}
​
data
object
Proposal metadata. This data is used to fill in variables in the description. Metadata is preserved when a draft is sent, making it ideal for attaching custom data to proposals.
​
invoicing_enabled
boolean
Enable invoicing for this proposal. When set to true, invoicing details (company name, organization number, address, etc.) can be added on the active proposal.
​
tax_options
object
Configure tax-related settings for the proposal. This determines how taxes are displayed and calculated in the proposal.
{
  mode?: 'standard' | 'simplified' | 'tax-free' | 'none'
  tax_included?: boolean
  tax_label_key?: string
}
mode: Controls the tax behavior for the proposal:
  • standard (Recommended): Products have tax/VAT values, and the footer shows totals with and without tax/VAT
  • simplified: Proposal-level setting determines if prices include or exclude tax. Footer only mentions if prices are including/excluding tax
  • tax-free: A special tax mode where taxes are exempt at a legal level. A specific message is shown in the footer
  • none: No tax information is displayed at all
tax_included: Determines whether taxes are included in the displayed prices. For standard mode, this changes which price is displayed. For simplified mode, this determines the footer message.tax_label_key: Custom label for how taxes are referred to in your region (e.g., “Tax” for American companies, “VAT” for European ones).
​
blocks
array
A list of blocks to be added to the draft. The content_id must be the variation_id of the product in the content library. Additional block data can be passed to overwrite the content library defaults.Video blocks can be added either by referencing a video from the content library using content_id and type: 'video-block', or by passing in the video url, title, and setting the block type to video-block.Needs to satisfy this shape:
(
  { content_id: number, type?: 'product-block' | 'video-block' } |
  {
    type: 'video-block',
    video_url: string,
    title: string,
  }
)[]
​
attachments
array
A list of attachments to be added to the draft. Attachments can be provided in three ways, and you can mix different types in a single request:1. Reference from Content Library - Reuse existing attachments without re-uploading:
{ id: number }
The attachment will be fetched from your content library. Access control is enforced - the attachment must belong to your company or be shared via content providers.2. HTML Link - Store a URL directly without uploading:
{ mime_type: 'text/html', name: string, url: string }
The URL is stored as-is and displayed as a clickable link.3. PDF Upload - Upload a file from a URL:
{ mime_type: 'application/pdf', name: string, url: string }
The file will be fetched from the URL and hosted reliably by Proposales.Example with mixed attachment types:
[
  { id: 123 },  // Reuse from content library
  { mime_type: 'text/html', name: 'Documentation', url: 'https://example.com/docs' },
  { mime_type: 'application/pdf', name: 'Terms', url: 'https://example.com/terms.pdf' }
]

​
Response

​
proposal
object