Add an Area to a Proposal

POST /public/proposals//area — Creates a named area (room) in a proposal. Auto-creates a default Draft option. Returns full proposal detail.

Use this endpoint to add a new area (such as a room or zone) to an existing proposal. Area names must be unique within the proposal. When the area is created, the system automatically generates one default option under it with a status of “Draft” — you do not need to create the first option manually. The response returns the complete updated proposal, including the new area and its default option.

Request

POST /public/proposals/{ProposalId}/area

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) to add the area to.

Body

Name · string · required

The display name for the new area (e.g., Living Room, Master Bedroom). Must be unique within the proposal.

Response

200 Success

Returns the full updated proposal detail, including the newly created area and its automatically generated default option. 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, including the newly added area.

areas[].id · integer

Unique identifier of the area.

areas[].name · string

Display name of the area.

areas[].options · array

Options within the area. The default option is created automatically 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	An area with the same name already exists on this proposal.
401	Not authorized. Invalid or missing HMAC authentication headers.
402	Active subscription required.
403	You do not have permission for this action.
404	Proposal not found.
409	Proposal state prevents editing.

Example

curl

curl -i -X POST \
  'https://api.portal.io/public/proposals/{ProposalId}/area' \
  -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 'Name=Living+Room'

200

{
  "id": 123,
  "lastModifiedDate": "2026-04-06T00:22:19Z",
  "areas": [
    {
      "id": 55,
      "name": "Living Room",
      "options": [
        {
          "id": 201,
          "status": "Draft",
          "clientDescription": null,
          "installerDescription": null
        }
      ]
    }
  ]
}