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>'

​
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.
​
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 API token user will be used as the contact person by default. This field is useful when multiple users share the same API token and you want to track who actually created the proposal.Note: This is different from recipient.email - the recipient is the customer receiving the proposal, while the contact person is the salesperson/account manager from your company.
​
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 also be added, by passing in the video url, title, and setting the block type to video-block.Needs to satisfy this shape:
(
  { content_id: number } |
  {
    type: 'video-block',
    video_url: string,
    title: string,
  }
)[]
​
attachments
array
A list of attachments to be added to the draft. Attachments will be fetched from the provided URL and hosted reliably by Proposales.Needs to be this shape:
{
  mime_type: string
  name: string
  url: string
}[]

​
Response

​
proposal
object