Skip to main content
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.
​
id
integer
required
Unique identifier of the proposal.
​
lastModifiedDate
string
ISO 8601 timestamp of the most recent modification.
​
areas
array
All areas on the proposal.
​
areas[].options
array
Options within the area, including the newly added option with status: "Draft".

​
Error Codes

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

​
Example

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'

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