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.
}
Possible errors:
Create proposal cover
POST /proposal/cover/createExample response
{
"status": "success",
"data": {}, // This object depends on created cover's details.
}
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