Add an Option to a Proposal Area

POST …/area//option — Adds a Draft option to a proposal area. Max 3 options per area. Accepts an optional client description and installer notes.

Use this endpoint to add a new option to an existing proposal area. Options allow you to present multiple installation configurations within a single area — for example, a standard package and a premium package for the same room. The new option is created with “Draft” status, and you can optionally provide a client-facing description and internal installer notes at creation time.

Each area already has one default option created automatically when the area is added. Use this endpoint to add up to 2 more options, for a maximum of 3 per area. Attempting to add a fourth option returns 400.

Request

POST /public/proposals/{ProposalId}/area/{AreaId}/option

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.

X-MSS-CUSTOM-DATE · string · required

Current UTC timestamp in RFC 7231 format.

X-MSS-SIGNATURE · string · required

HMAC-SHA256 signature, Base64-encoded.

Path Parameters

ProposalId · integer · required

The unique ID of the proposal (not the proposal number).

AreaId · integer · required

The unique ID of the area to add an option to.

Body

ClientDescription · string

Optional client-facing description shown to customers on proposal documents (e.g., Premium Installation Package). Keep it concise and customer-focused.

InternalNotes · string

Optional internal notes for the installer team. Not shown on client-facing documents.

Response

200 Success

Returns the full updated proposal detail, including the newly created option under the specified area. See Get Proposal for the complete field reference. Key fields:

id · integer · required

Unique identifier of 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.

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.

financialSummary · object · required

Full financial breakdown. See Get Proposal for field details.

areas · array

All areas on the proposal.

areas[].options · array

Options within the area, including the newly added option with status: "Draft".

dealer · object · required

Dealer account details.

lastModifiedUser · object · required

Details of the user who last modified the proposal.

Error Codes

Code	Meaning
400	This area already has the maximum of 3 options.
401	Not authorized. Invalid or missing HMAC authentication headers.
402	Active subscription required.
403	You do not have permission for this action.
404	Proposal or area not found.
409	Proposal state prevents editing.

Example

curl

curl -i -X POST \
  'https://api.portal.io/public/proposals/123/area/55/option' \
  -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 'ClientDescription=Premium+Installation+Package' \
  -d 'InternalNotes=Use+18-gauge+wire+throughout'

200

{
  "id": 123,
  "lastModifiedDate": "2026-04-06T00:22:19Z",
  "areas": [
    {
      "id": 55,
      "name": "Living Room",
      "options": [
        {
          "id": 201,
          "status": "Draft",
          "clientDescription": null,
          "installerDescription": null
        },
        {
          "id": 202,
          "status": "Draft",
          "clientDescription": "Premium Installation Package",
          "installerDescription": "Use 18-gauge wire throughout"
        }
      ]
    }
  ]
}