Update an Area Option's Client Description

POST …/area-options//clientdescription — Sets the customer-facing description for an area option. Returns the full updated proposal detail.

Use this endpoint to set or update the client-facing description for a specific area option. This description appears on customer-facing proposal documents and helps the customer understand what each option includes. The route requires both the proposal ID and the area option ID to verify that the option belongs to the specified proposal before applying the update.

Request

POST /public/proposals/{ProposalId}/area-options/{AreaOptionId}/clientdescription

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 the area option belongs to.

AreaOptionId · integer · required

The unique ID of the area option to update.

Body

ClientDescription · string

The client-facing description for the option. This text is displayed to customers on proposal documents. Submit an empty string to clear the description.

Response

200 Success

Returns the full updated proposal detail reflecting the new client description. 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, with the updated option reflecting the new clientDescription.

dealer · object · required

Dealer account details.

lastModifiedUser · object · required

Details of the user who last modified the proposal.

Error Codes

Code	Meaning
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 option not found.
409	Proposal is in a state that does not allow editing.

Example

curl

curl -i -X POST \
  'https://api.portal.io/public/proposals/123/area-options/201/clientdescription' \
  -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=Standard+Installation+Package'

200

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