Create a New Proposal

POST /public/proposals — Creates a new proposal. Requires a SalesPersonId; name is optional. Returns full proposal detail including the financial summary.

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.

number · integer · required

Proposal number unique within the dealer account.

name · string · required

Display name of the proposal.

status · string · required

Current proposal status. One of Undefined, Draft, Submitted, ViewedByClient, Accepted, Declined, Delayed, Completed, EmailFailed, Expired. Newly created proposals start as Draft.

createdDate · string · required

ISO 8601 timestamp when the proposal was created.

lastModifiedDate · string · required

ISO 8601 timestamp of the most recent modification.

lastModifiedByUserDate · string · required

ISO 8601 timestamp when the proposal was last modified by a human user.

lastSubmittedDate · string

ISO 8601 timestamp when the proposal was last submitted to the client. Null if never submitted.

clientLastOpenedDate · string

ISO 8601 timestamp when the client last opened the proposal. Null if never opened.

clientLastDecisionDate · string

ISO 8601 timestamp when the client last accepted or declined the proposal. Null if no decision made.

lastCompletedDate · string

ISO 8601 timestamp when the proposal was last marked as completed. Null if never completed.

financialSummary · object · required

Calculated totals for the proposal. All values are zero for a newly created proposal.

Show Financial summary fields

financialSummary.partsSubtotal · number

Subtotal for all parts before discounts.

financialSummary.partsTotal · number

Parts total after discounts.

financialSummary.laborTotal · number

Total labor charges.

financialSummary.feeTotal · number

Total fees.

financialSummary.proposalSubtotal · number

Subtotal before tax.

financialSummary.salesTax.total · number

Calculated sales tax amount.

financialSummary.proposalTotal · number

Grand total including tax.

areas · array

The proposal’s areas (rooms). Empty array for a newly created proposal.

changeOrders · array

Change orders associated with this proposal. Empty for a newly created proposal.

customer · object

Customer contact assigned to this proposal. Null until a contact is assigned via the assign-contact endpoint.

dealer · object · required

Dealer account details for the account that owns this proposal.

coverpageImageUrl · string

Absolute URL of the proposal cover image. Null when no cover image is set.

aboutUs · string

The about us text from the company profile.

projectDescription · string

Client-facing description of the project.

profit · object

Profit summary for the proposal.

recurringServices · object

Recurring service plan details associated with the proposal.

paymentSchedule · object

Payment schedule configuration for the proposal.

paymentRequests · array

Payment requests issued for this proposal.

projectTerms · string

Terms and conditions for the project.

lastModifiedUser · object · required

Details of the user who last modified the proposal.

Error Codes

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

Example

curl

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'

200

{
  "id": 1042,
  "number": 1005,
  "name": "Smith Residence AV",
  "status": "Draft",
  "createdDate": "2026-04-06T00:22:19Z",
  "lastModifiedDate": "2026-04-06T00:22:19Z",
  "lastModifiedByUserDate": "2026-04-06T00:22:19Z",
  "lastSubmittedDate": null,
  "clientLastOpenedDate": null,
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "financialSummary": {
    "partsSubtotal": 0,
    "partsTotal": 0,
    "laborTotal": 0,
    "feeTotal": 0,
    "proposalSubtotal": 0,
    "salesTax": {
      "taxStatus": "Undefined",
      "total": 0
    },
    "proposalTotal": 0
  },
  "areas": [],
  "changeOrders": [],
  "customer": null,
  "dealer": {
    "id": 5,
    "name": "AV Solutions Inc."
  },
  "coverpageImageUrl": null,
  "aboutUs": null,
  "projectDescription": null,
  "profit": null,
  "recurringServices": null,
  "paymentSchedule": null,
  "paymentRequests": [],
  "projectTerms": null,
  "lastModifiedUser": {
    "id": 42,
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}