Skip to main content
Creates a new proposal under the authenticated account. You must supply the ID of a salesperson (user) who belongs to the same account. If no name is provided, the system assigns a default name using the same naming logic as the Portal.io UI. The response returns the complete proposal detail object, including the new proposal’s ID, number, status, and financial summary.

​
Request

POST /public/proposals

​
Headers

​
Accept
string
required
Must be application/json.
​
Content-Type
string
required
Must be application/x-www-form-urlencoded.
​
X-MSS-API-APPID
string
required
Your API Application Key.
​
X-MSS-API-USERKEY
string
required
Your User API Key obtained from the authentication exchange.
​
X-MSS-CUSTOM-DATE
string
required
Current UTC timestamp in RFC 7231 format, e.g. Mon, 06 Apr 2026 00:22:19 GMT.
​
X-MSS-SIGNATURE
string
required
HMAC-SHA256 signature of the canonical request message, Base64-encoded.

​
Body Parameters

​
SalesPersonId
integer
required
The ID of the salesperson (user) who will own the proposal. Must be a user in the current account.
​
Name
string
Display name for the new proposal. If omitted, the system assigns a default name.

​
Response

​
200 Success

​
id
integer
required
Unique numeric ID of the new proposal. Use this value in all subsequent calls that reference the proposal.
​
createdDate
string
ISO 8601 timestamp when the proposal was created.
​
lastModifiedDate
string
ISO 8601 timestamp of the most recent modification.
​
financialSummary
object
Calculated totals for the proposal.

​
Error Codes

CodeMeaning
401Not authorized. Check that your HMAC signature and headers are correct.
402The account’s subscription is inactive or expired.
403Your user does not have permission to create proposals.
404The specified SalesPersonId was not found in the current account.

​
Example

curl -i -X POST \
  'https://sandbox.api.portal.io/public/proposals' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-MSS-API-APPID: YOUR_APP_ID' \
  -H 'X-MSS-API-USERKEY: YOUR_USER_KEY' \
  -H 'X-MSS-CUSTOM-DATE: Mon, 06 Apr 2026 00:22:19 GMT' \
  -H 'X-MSS-SIGNATURE: BASE64_SIGNATURE' \
  -d 'SalesPersonId=42' \
  -d 'Name=Smith+Residence+AV'

{
  "id": 1042,
  "createdDate": "2026-04-06T00:22:19Z",
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "lastModifiedDate": "2026-04-06T00:22:19Z",
  "lastModifiedByUserDate": "2026-04-06T00:22:19Z",
  "financialSummary": {
    "partsSubtotal": 0,
    "partsDiscountType": "Percentage",
    "partsDiscountPercentage": 0,
    "partsDiscount": 0,
    "partsTotal": 0,
    "laborTotal": 0,
    "feeTotal": 0,
    "proposalSubtotal": 0,
    "salesTax": {
      "taxStatus": "Undefined",
      "total": 0
    },
    "proposalTotal": 0
  }
}