Better Proposals API
Beta
Contents
Introduction
Errors
Authentication
Proposals
Templates
Document Types
Companies
Currencies
Settings
Better Proposals API
Beta
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 02:
Errors and debugging
Handling API errors.
Reponse types
Better Proposals API always return a JSON as response body.
It always include a status key, which can have two values:
success or error
With that you can simply know your request has succeeded or not.
If status is "success" then it always have a key called data, where your requested information is stored.
Global Errors
Malformed Request
This error means that request you sent to the server is not correctly formed. Mostly this kind of error appears when you don't pass access token to request headers
{
"status": "error",
"message": "Malformed request"
}
Invalid token
This error appears when the token you passed is not valid anymore. View API Authentication details
{
"status": "error",
"message": "Invalid token"
}
Trial expired
This error appears when your free trial ends. To continue using our API, you should upgrade to Premium or Enterprise plans.
{
"status": "error",
"message": "Your trial has expired."
}
Current Plan Not Supported
After your free trial, you can only use Better Proposals API with Premium or Enterprise plans. This error indicates that your current plan doesn't support API usage.
{
"status": "error",
"message": "It isn't possible to use the Better Proposals API on your current plan."
}
Page not found
This error appears when 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 |
|---|---|
| 2XX | Success |
| 4XX | Client error |
| 5XX | 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
We currently support only header authorization type.
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 05:
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 06:
Currencies
Getting currencies
Get all currencies
GET /currencyExample response
Get currency details
GET /currency/:CURRENCY_IDExample response
Section 07:
