Better Proposals API
Contents
Introduction
Errors
Authentication
Proposals
Templates
Document Types
Companies
Currencies
Settings
Better Proposals API
Contents
Introduction
Errors
Authentication
Proposals
Templates
Document Types
Companies
Currencies
Settings
Getting started
Introduction
Get started integrating with Better Proposals using our API.
Everything you need from instructions to code examples is inside.
Let's get started
Section 01:
Errors and debugging
Handling API errors
Reponse types
The Better Proposals API always returns a JSON as the response body.
The response always includes a status key, which can have one of two values:
success or error
That lets you know whether your request was successful.
If the status is "success", the response will always include a data key containing the requested information.
Global Errors
Malformed Request
This error means that the request you've sent to the server is not formatted correctly.
This type of error usually occurs when you don't include the access token in the request headers.
{
"status": "error",
"message": "Malformed request"
}
Invalid token
This error occurs when the token you passed is not valid anymore. View API Authentication details
{
"status": "error",
"message": "Invalid token"
}
Trial expired
This error occurs when your free trial ends.
To continue using our API, you need to upgrade to the Premium or Enterprise plan.
{
"status": "error",
"message": "Your trial has expired."
}
Current Plan Not Supported
After your free trial, you can only use the Better Proposals API on the Premium or Enterprise plan. This error indicates that your current plan doesn't support API use.
{
"status": "error",
"message": "It isn't possible to use the Better Proposals API on your current plan."
}
Page not found
This error occurs when an endpoint url is not found or is not available in the current version of the API.
You can view available API endpoints in the API documentation menu.
{
"status": "error",
"message": "Not found"
}
Response status codes
| Status code | Description | ||
|---|---|---|---|
| Status code | 2XX | Description | Success |
| Status code | 4XX | Description | Client error |
| Status code | 5XX | Description | Server error |
Section 02:
API Authentication
Getting your app and Better Proposals talking to each other
Get your API token
- Log in to your Better Proposals account
- Click here to access the API key generator
- Click the “Generate API Key” button
- The page will display API Key/Token
- You can also regenerate your existing API Key/Token
Include API token in request
The API currently supports header authorization.
Simply include Bptoken: YOUR_API_TOKEN in your request headers.
Example: Get all proposals
GET /proposalExample response
Possible errors:
Invalid API Token
Bad Request
Section 03:
Proposals
Getting Proposal data and creating proposals
Get all proposals
GET /proposalExample response
Get new proposals
GET /proposal/newExample response
Get opened proposals
GET /proposal/openedExample response
Get sent proposals
GET /proposal/sentExample response
Get signed proposals
GET /proposal/signedExample response
Get paid proposals
GET /proposal/paidExample response
Get proposal details
GET /proposal/:PROPOSAL_IDExample response
Get total proposals
GET /proposal/countExample response
Create proposal
POST /proposal/create
$url = "https://api.betterproposals.io/proposal/create/";
$headers = [
"Bptoken: YOUR_API_TOKEN"
];
$data = http_build_query([
"Company" => "COMPANY_ID_OR_NAME",
"Cover" => "COVER_ID",
"Template" => "TEMPLATE_ID",
"DocumentType" => "DOCUMENT_TYPE_ID_OR_NAME" // Default is Proposal
"Brand" => "BRAND_ID",
"Currency" => "CURRENCY", // For example "usd"
"Tax" => true,
"TaxLabel" => "TaxLabel",
"TaxAmount" => "TaxAmount",
"Contacts" => [
[
"FirstName" => "John",
"Surname" => "Doe",
"Email" => "john@doe.com",
"Signature" => true,
]
],
"MergeTags" => "[{'tag': 'some_tag', 'value': 'Some Value'}]"
]);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $headers,
]);
$response = curl_exec($curl);
$result = json_decode($response);
// Example using 'request' module.
var request = require('request');
var options = {
url: "https://api.betterproposals.io/proposal/create/",
headers: {
Bptoken: "YOUR_API_TOKEN"
},
form: {
Company : "COMPANY_ID_OR_NAME",
Cover : "COVER_ID",
Template : "TEMPLATE_ID",
DocumentType : "DOCUMENT_TYPE_ID_OR_NAME" // Default is Proposal
Brand : "BRAND_ID",
Currency : "CURRENCY", // For example "usd"
Tax : true,
TaxLabel : "TaxLabel",
TaxAmount : "TaxAmount",
Contacts : [{
FirstName : "John",
Surname : "Doe",
Email : "john@doe.com",
Signature : true,
}],
MergeTags : "[{"tag": "some_tag", "value": "Some Value}]"
}
};
function callback(error, response, body) {
var result = JSON.parse(body);
// Do stuff with result.
};
request.post(options, callback);
Example response
{
"status": "success",
"data": {
// This object depends on created proposal's details, plus the links:
"ProposalView": "https://betterproposals.io/2/proposals/view?id=...",
"Preview": "https://betterproposals.io/proposal/index?ProposalID=...",
"Editor": "https://betterproposals.io/2/editor/proposal-editor?id=..." // Open the document in the editor to check and edit it
}
}
Possible errors:
Create proposal cover
POST /proposal/cover/createExample response
{
"status": "success",
"data": {}, // This object depends on created cover's details.
}
Possible errors:
Edit proposal
POST /proposal/editUpdates the settings of an existing proposal. Only the provided fields are changed. When Contacts are provided they replace the existing ones, following the same rules as the recipients on the send page: contacts that already signed are never removed or modified.
$url = "https://api.betterproposals.io/proposal/edit/";
$headers = [
"Bptoken: YOUR_API_TOKEN"
];
$data = http_build_query([
"ID" => "PROPOSAL_ID",
"Company" => "COMPANY_ID_OR_NAME",
"Cover" => "COVER_ID",
"DocumentType" => "DOCUMENT_TYPE_ID_OR_NAME",
"Brand" => "BRAND_ID",
"Currency" => "CURRENCY", // For example "usd"
"Tax" => true,
"TaxLabel" => "TaxLabel",
"TaxAmount" => "TaxAmount",
"Description" => "New description",
"Contacts" => [
[
"FirstName" => "John",
"Surname" => "Doe",
"Email" => "john@doe.com",
"Signature" => true,
]
],
"MergeTags" => "[{'tag': 'some_tag', 'value': 'Some Value'}]"
]);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $headers,
]);
$response = curl_exec($curl);
$result = json_decode($response);
// Example using 'request' module.
var request = require('request');
var options = {
url: "https://api.betterproposals.io/proposal/edit/",
headers: {
Bptoken: "YOUR_API_TOKEN"
},
form: {
ID : "PROPOSAL_ID",
Company : "COMPANY_ID_OR_NAME",
Cover : "COVER_ID",
DocumentType : "DOCUMENT_TYPE_ID_OR_NAME",
Brand : "BRAND_ID",
Currency : "CURRENCY", // For example "usd"
Tax : true,
TaxLabel : "TaxLabel",
TaxAmount : "TaxAmount",
Description : "New description",
Contacts : [{
FirstName : "John",
Surname : "Doe",
Email : "john@doe.com",
Signature : true,
}],
MergeTags : "[{"tag": "some_tag", "value": "Some Value}]"
}
};
function callback(error, response, body) {
var result = JSON.parse(body);
// Do stuff with result.
};
request.post(options, callback);
Example response
{
"status": "success",
"data": {
// This object depends on edited proposal's details, plus the links:
"ProposalView": "https://betterproposals.io/2/proposals/view?id=...",
"Preview": "https://betterproposals.io/proposal/index?ProposalID=...",
"Editor": "https://betterproposals.io/2/editor/proposal-editor?id=..." // Open the document in the editor to check and edit it
}
}
Possible errors:
Edit proposal cover
POST /proposal/cover/editExample response
{
"status": "success",
"data": {}, // This object depends on edited cover's details.
}
Possible errors:
Add or edit pricing block
POST /proposal/block/pricingAdds the pricing block to a proposal with its pricing tables and line items, exactly like the editor does. A document can contain only one pricing block: when the document already has one (for example because it was created from a template) the request edits it instead, so the same endpoint adds and updates pricing. When the block is added it goes in an existing section (Section = section ID), in a new section (Section = name of the new section) or in a new untitled section, at the end of the section or at the given Position.
Tables and line items without an ID are created. Tables and line items with an ID (returned by this endpoint and by Get proposal details) are updated with the provided fields, or deleted when they carry Delete: true. Changing the UnitCost or Quantity of a line item recalculates its total, changing the Cost recalculates its unit cost. The quote totals of the document are recalculated after every change.
$url = "https://api.betterproposals.io/proposal/block/pricing/";
$headers = [
"Bptoken: YOUR_API_TOKEN"
];
$data = http_build_query([
"ID" => "PROPOSAL_ID",
"Section" => "Investment", // Section ID or name of a new section, used when the block is added
"Title" => "Your investment",
"Tables" => json_encode([
[
"Title" => "Services",
"Items" => [
[
"Label" => "Website design",
"Description" => "Design of the new website",
"UnitCost" => 1000,
"Quantity" => 1,
"RecurringType" => "one-off" // one-off, monthly, quarterly, annual
],
[
"Label" => "Hosting",
"UnitCost" => 50,
"RecurringType" => "monthly",
"Optional" => true
]
]
],
[
"ID" => "EXISTING_TABLE_ID", // Edits an existing table
"Title" => "Support",
"Items" => [
["ID" => "EXISTING_ITEM_ID", "UnitCost" => 1200], // Edits an existing line item
["ID" => "ANOTHER_ITEM_ID", "Delete" => true], // Deletes a line item
["Label" => "Training", "UnitCost" => 300] // Adds a line item to the table
]
]
])
]);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $headers,
]);
$response = curl_exec($curl);
$result = json_decode($response);
// Example using 'request' module.
var request = require('request');
var options = {
url: "https://api.betterproposals.io/proposal/block/pricing/",
headers: {
Bptoken: "YOUR_API_TOKEN"
},
form: {
ID : "PROPOSAL_ID",
Section : "Investment",
Title : "Your investment",
Tables : JSON.stringify([
{
Title : "Services",
Items : [
{
Label : "Website design",
Description : "Design of the new website",
UnitCost : 1000,
Quantity : 1,
RecurringType : "one-off"
},
{
Label : "Hosting",
UnitCost : 50,
RecurringType : "monthly",
Optional : true
}
]
},
{
ID : "EXISTING_TABLE_ID",
Title : "Support",
Items : [
{ ID : "EXISTING_ITEM_ID", UnitCost : 1200 },
{ ID : "ANOTHER_ITEM_ID", Delete : true },
{ Label : "Training", UnitCost : 300 }
]
}
])
}
};
function callback(error, response, body) {
var result = JSON.parse(body);
// Do stuff with result.
};
request.post(options, callback);
Example response
{
"status": "success",
"data": {
"ProposalID": 12345,
"Action": "created", // "updated" when the document already had a pricing block
"PageID": 111,
"PageName": "Investment",
"NewSection": true,
"Block": {
"Type": "pricing",
"ElementType": "quote",
"ElementID": 222,
"ProposalElementID": 333,
"DisplayOrder": 1
},
"PriceTables": [
{
"ID": 444,
"Title": "Services",
"Show": true,
"ForceClientChoice": false,
"DateCreated": "2026-09-15 10:00:00",
"DisplayOrder": 1,
"Items": [
{
"ID": 555,
"Label": "Website design",
"Description": "Design of the new website",
"UnitCost": "1000.00",
"Cost": "1000.00",
"RecurringType": "One Time Payment",
"Quantity": 1,
"Optional": false,
"DisplayOrder": 1
// ... the same fields returned by Get proposal details
}
]
}
],
"Preview": "https://betterproposals.io/proposal/index?ProposalID=...",
"Editor": "https://betterproposals.io/2/editor/proposal-editor?id=..."
}
}
Possible errors:
Generate document links
POST /proposal/linksGenerates the personal link of every recipient of the proposal without sending any email, like the "generate the document link" option of the send page, so you can deliver the links yourself. Recipients are saved as document contacts with their signing order. Use RequiredToSign on each recipient to require their signature and SignOrder to force recipients to sign in the order they appear. Recipients that already signed cannot be removed or modified. If Recipients is omitted, the links are generated for the existing contacts of the document. Generating the links counts as a send: it counts towards the monthly sending limit of your plan and follows the same rules as the send page (documents pending approval can't be sent by users that require approval, and repeated sends of the same document in a short period are blocked).
$url = "https://api.betterproposals.io/proposal/links/";
$headers = [
"Bptoken: YOUR_API_TOKEN"
];
$data = http_build_query([
"ID" => "PROPOSAL_ID",
"SignOrder" => true, // Recipients must sign in the order they appear
"Recipients" => json_encode([
[
"FirstName" => "John",
"Surname" => "Doe",
"Email" => "john@doe.com",
"RequiredToSign" => true
],
[
"FirstName" => "Jane",
"Surname" => "Doe",
"Email" => "jane@doe.com",
"RequiredToSign" => false
]
])
]);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $headers,
]);
$response = curl_exec($curl);
$result = json_decode($response);
// Example using 'request' module.
var request = require('request');
var options = {
url: "https://api.betterproposals.io/proposal/links/",
headers: {
Bptoken: "YOUR_API_TOKEN"
},
form: {
ID : "PROPOSAL_ID",
SignOrder : true,
Recipients : JSON.stringify([
{
FirstName : "John",
Surname : "Doe",
Email : "john@doe.com",
RequiredToSign : true
},
{
FirstName : "Jane",
Surname : "Doe",
Email : "jane@doe.com",
RequiredToSign : false
}
])
}
};
function callback(error, response, body) {
var result = JSON.parse(body);
// Do stuff with result.
};
request.post(options, callback);
Example response
{
"status": "success",
"data": {
"ProposalID": 12345,
"SignOrder": true,
"DateSent": "2026-09-15 10:00:00",
"Recipients": [
{
"FirstName": "John",
"Surname": "Doe",
"Email": "john@doe.com",
"RequiredToSign": true,
"Link": "https://betterproposals.io/proposal/index?ProposalID=...&ContactID=..."
},
{
"FirstName": "Jane",
"Surname": "Doe",
"Email": "jane@doe.com",
"RequiredToSign": false,
"Link": "https://betterproposals.io/proposal/index?ProposalID=...&ContactID=..."
}
],
"ProposalView": "https://betterproposals.io/2/proposals/view?id=..."
}
}
Possible errors:
Section 04:
Templates
Getting Template information
Get all Templates
GET /templateExample response
Get template details
GET /template/:TEMPLATE_IDExample response
Section 05:
Document Types
Getting Document Type data and creating new Document Types
Get all document types
GET /doctypeExample response
Create document type
POST /doctype/create
$url = "https://api.betterproposals.io/doctype/create/";
$headers = [
"Bptoken: YOUR_API_TOKEN"
];
$data = http_build_query([
"TypeName" => "TYPE_NAME",
"TypeColour" => "SOME_HEX_CODE",
]);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $headers,
]);
$response = curl_exec($curl);
$result = json_decode($response);
// Example using 'request' module.
var request = require('request');
var options = {
url: "https://api.betterproposals.io/doctype/create/",
headers: {
Bptoken: "YOUR_API_TOKEN"
},
form: {
TypeName : "TYPE_NAME",
TypeColour : "SOME_HEX_CODE",
}
};
function callback(error, response, body) {
var result = JSON.parse(body);
// Do stuff with result.
};
request.post(options, callback);
Example response
Possible errors:
Section 05:
Quotes
Some text for quotes here.
Get all quotes
GET /quoteExample response
Get quote details
GET /quote/:QUOTE_IDExample response
Create quote
POST /quote/createExample response
{
"status": "success",
"data": {}, // This object depends on created quote's details.
}
Section 06:
Companies
Getting company information and creating new companies
Get all companies
GET /companyExample response
Get company details
GET /company/:COMPANY_IDExample response
Create company
POST /company/createExample response
{
"status": "success",
"data": {}, // This object depends on created company's details.
}
Section 07:
Currencies
Getting currencies
Get all currencies
GET /currencyExample response
Get currency details
GET /currency/:CURRENCY_IDExample response
Section 08:
Settings
Getting information from Settings
Get settings
GET /settingsExample response
Get settings of brand
GET /settings/brandExample response
Get custom merge tags
GET /settings/merge_tagExample response
Better Proposals API Docs
Go to your account
Sign up free to Better Proposals