Get Proposal Details

curl -i -X GET \
  'https://sandbox.api.portal.io/public/proposals/1042' \
  -H 'Accept: application/json' \
  -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'

import requests
from portal_auth import sign_request  # See authentication guide

url = "https://sandbox.api.portal.io/public/proposals/1042"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
signature = sign_request("GET", url, "", timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.get(url, headers={
    "Accept": "application/json",
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
})
print(response.json())

const { signRequest } = require('./portalAuth'); // See authentication guide

const url = "https://sandbox.api.portal.io/public/proposals/1042";
const timestamp = new Date().toUTCString();
const signature = signRequest("GET", url, "", timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    headers: {
        "Accept": "application/json",
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    }
});
const data = await response.json();
console.log(data);

{
  "id": 1042,
  "number": 1001,
  "name": "Smith Residence AV",
  "status": "Draft",
  "createdDate": "2026-03-10T14:00:00Z",
  "lastModifiedDate": "2026-04-01T09:30:00Z",
  "lastModifiedByUserDate": "2026-04-01T09:30:00Z",
  "lastSubmittedDate": null,
  "clientLastOpenedDate": null,
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "financialSummary": {
    "partsSubtotal": 8000.00,
    "partsTotal": 8000.00,
    "laborTotal": 2500.00,
    "feeTotal": 0,
    "proposalSubtotal": 10500.00,
    "salesTax": {
      "taxStatus": "Ok",
      "total": 892.50
    },
    "proposalTotal": 11392.50
  },
  "areas": [
    {
      "id": 55,
      "name": "Living Room",
      "options": [
        {
          "id": 201,
          "status": "Draft",
          "lastModifiedDate": "2026-04-01T09:30:00Z",
          "clientDescription": "Standard package",
          "installerDescription": "Use 18-gauge wire throughout",
          "total": 2095.50,
          "totalRecurringService": 0,
          "items": [
            {
              "id": 5001,
              "parentId": null,
              "itemType": "Part",
              "referencedItemId": 88213,
              "createdDate": "2026-03-10T14:05:00Z",
              "lastModifiedDate": "2026-04-01T09:30:00Z",
              "brand": "Sonos",
              "model": "Amp",
              "name": null,
              "shortDescription": "Sonos Amp",
              "clientNote": null,
              "imageUrl": "https://images.portal.io/catalog/sonos-amp.jpg",
              "msrp": 699.00,
              "sellPrice": 649.00,
              "cost": 499.00,
              "costUpdateDate": "2026-04-01T00:00:00Z",
              "supplier": "Sonos Inc.",
              "quantity": 2,
              "total": {
                "amount": 1298.00,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            },
            {
              "id": 5002,
              "parentId": 5001,
              "itemType": "Part",
              "referencedItemId": 90144,
              "createdDate": "2026-03-10T14:06:00Z",
              "lastModifiedDate": "2026-03-10T14:06:00Z",
              "brand": "Sonance",
              "model": "VP62R",
              "name": null,
              "shortDescription": "Sonance VP62R In-Ceiling Speaker",
              "clientNote": null,
              "imageUrl": null,
              "msrp": 179.00,
              "sellPrice": 137.50,
              "cost": 98.00,
              "costUpdateDate": "2026-04-01T00:00:00Z",
              "supplier": "ADI Global Distribution",
              "quantity": 4,
              "total": {
                "amount": 550.00,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            },
            {
              "id": 5003,
              "parentId": null,
              "itemType": "Labor",
              "referencedItemId": 730,
              "createdDate": "2026-03-10T14:08:00Z",
              "lastModifiedDate": "2026-03-10T14:08:00Z",
              "brand": null,
              "model": null,
              "name": "Installation Labor",
              "shortDescription": "Installation Labor",
              "clientNote": null,
              "imageUrl": null,
              "msrp": null,
              "sellPrice": 45.00,
              "cost": null,
              "costUpdateDate": null,
              "supplier": null,
              "quantity": 5.5,
              "total": {
                "amount": 247.50,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            }
          ]
        },
        {
          "id": 202,
          "status": "Draft",
          "lastModifiedDate": "2026-03-28T16:12:00Z",
          "clientDescription": "Premium Installation Package",
          "installerDescription": null,
          "total": 3450.00,
          "totalRecurringService": 25.00,
          "items": []
        }
      ]
    }
  ],
  "changeOrders": [],
  "customer": {
    "id": 88,
    "firstName": "Jane",
    "lastName": "Smith",
    "companyName": "",
    "contactEmail": "jane.smith@example.com"
  },
  "dealer": {
    "id": 5,
    "name": "AV Solutions Inc."
  },
  "coverpageImageUrl": null,
  "aboutUs": "We specialize in smart home integration.",
  "projectDescription": "Whole-home AV and lighting control system.",
  "profit": null,
  "recurringServices": null,
  "paymentSchedule": null,
  "paymentRequests": [],
  "projectTerms": "Payment due within 30 days of completion.",
  "lastModifiedUser": {
    "id": 12,
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}

GET

public

proposals

{ProposalId}

curl -i -X GET \
  'https://sandbox.api.portal.io/public/proposals/1042' \
  -H 'Accept: application/json' \
  -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'

import requests
from portal_auth import sign_request  # See authentication guide

url = "https://sandbox.api.portal.io/public/proposals/1042"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
signature = sign_request("GET", url, "", timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.get(url, headers={
    "Accept": "application/json",
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
})
print(response.json())

const { signRequest } = require('./portalAuth'); // See authentication guide

const url = "https://sandbox.api.portal.io/public/proposals/1042";
const timestamp = new Date().toUTCString();
const signature = signRequest("GET", url, "", timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    headers: {
        "Accept": "application/json",
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    }
});
const data = await response.json();
console.log(data);

{
  "id": 1042,
  "number": 1001,
  "name": "Smith Residence AV",
  "status": "Draft",
  "createdDate": "2026-03-10T14:00:00Z",
  "lastModifiedDate": "2026-04-01T09:30:00Z",
  "lastModifiedByUserDate": "2026-04-01T09:30:00Z",
  "lastSubmittedDate": null,
  "clientLastOpenedDate": null,
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "financialSummary": {
    "partsSubtotal": 8000.00,
    "partsTotal": 8000.00,
    "laborTotal": 2500.00,
    "feeTotal": 0,
    "proposalSubtotal": 10500.00,
    "salesTax": {
      "taxStatus": "Ok",
      "total": 892.50
    },
    "proposalTotal": 11392.50
  },
  "areas": [
    {
      "id": 55,
      "name": "Living Room",
      "options": [
        {
          "id": 201,
          "status": "Draft",
          "lastModifiedDate": "2026-04-01T09:30:00Z",
          "clientDescription": "Standard package",
          "installerDescription": "Use 18-gauge wire throughout",
          "total": 2095.50,
          "totalRecurringService": 0,
          "items": [
            {
              "id": 5001,
              "parentId": null,
              "itemType": "Part",
              "referencedItemId": 88213,
              "createdDate": "2026-03-10T14:05:00Z",
              "lastModifiedDate": "2026-04-01T09:30:00Z",
              "brand": "Sonos",
              "model": "Amp",
              "name": null,
              "shortDescription": "Sonos Amp",
              "clientNote": null,
              "imageUrl": "https://images.portal.io/catalog/sonos-amp.jpg",
              "msrp": 699.00,
              "sellPrice": 649.00,
              "cost": 499.00,
              "costUpdateDate": "2026-04-01T00:00:00Z",
              "supplier": "Sonos Inc.",
              "quantity": 2,
              "total": {
                "amount": 1298.00,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            },
            {
              "id": 5002,
              "parentId": 5001,
              "itemType": "Part",
              "referencedItemId": 90144,
              "createdDate": "2026-03-10T14:06:00Z",
              "lastModifiedDate": "2026-03-10T14:06:00Z",
              "brand": "Sonance",
              "model": "VP62R",
              "name": null,
              "shortDescription": "Sonance VP62R In-Ceiling Speaker",
              "clientNote": null,
              "imageUrl": null,
              "msrp": 179.00,
              "sellPrice": 137.50,
              "cost": 98.00,
              "costUpdateDate": "2026-04-01T00:00:00Z",
              "supplier": "ADI Global Distribution",
              "quantity": 4,
              "total": {
                "amount": 550.00,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            },
            {
              "id": 5003,
              "parentId": null,
              "itemType": "Labor",
              "referencedItemId": 730,
              "createdDate": "2026-03-10T14:08:00Z",
              "lastModifiedDate": "2026-03-10T14:08:00Z",
              "brand": null,
              "model": null,
              "name": "Installation Labor",
              "shortDescription": "Installation Labor",
              "clientNote": null,
              "imageUrl": null,
              "msrp": null,
              "sellPrice": 45.00,
              "cost": null,
              "costUpdateDate": null,
              "supplier": null,
              "quantity": 5.5,
              "total": {
                "amount": 247.50,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            }
          ]
        },
        {
          "id": 202,
          "status": "Draft",
          "lastModifiedDate": "2026-03-28T16:12:00Z",
          "clientDescription": "Premium Installation Package",
          "installerDescription": null,
          "total": 3450.00,
          "totalRecurringService": 25.00,
          "items": []
        }
      ]
    }
  ],
  "changeOrders": [],
  "customer": {
    "id": 88,
    "firstName": "Jane",
    "lastName": "Smith",
    "companyName": "",
    "contactEmail": "jane.smith@example.com"
  },
  "dealer": {
    "id": 5,
    "name": "AV Solutions Inc."
  },
  "coverpageImageUrl": null,
  "aboutUs": "We specialize in smart home integration.",
  "projectDescription": "Whole-home AV and lighting control system.",
  "profit": null,
  "recurringServices": null,
  "paymentSchedule": null,
  "paymentRequests": [],
  "projectTerms": "Payment due within 30 days of completion.",
  "lastModifiedUser": {
    "id": 12,
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}

Returns complete detail for the specified proposal, including all areas, options, customer information, and a full financial summary. The HTTP response also sets a Last-Modified header derived from the proposal’s lastModifiedDate, which you can use for conditional request patterns. This is also the only way to read a proposal’s line items: they are nested at areas[].options[].items[], and both the area option ids and item ids that the proposal item endpoints require come from here. See reading proposal items for what each item field means.

curl -i -X GET \
  'https://sandbox.api.portal.io/public/proposals/1042' \
  -H 'Accept: application/json' \
  -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'

import requests
from portal_auth import sign_request  # See authentication guide

url = "https://sandbox.api.portal.io/public/proposals/1042"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
signature = sign_request("GET", url, "", timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.get(url, headers={
    "Accept": "application/json",
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
})
print(response.json())

const { signRequest } = require('./portalAuth'); // See authentication guide

const url = "https://sandbox.api.portal.io/public/proposals/1042";
const timestamp = new Date().toUTCString();
const signature = signRequest("GET", url, "", timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    headers: {
        "Accept": "application/json",
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    }
});
const data = await response.json();
console.log(data);

{
  "id": 1042,
  "number": 1001,
  "name": "Smith Residence AV",
  "status": "Draft",
  "createdDate": "2026-03-10T14:00:00Z",
  "lastModifiedDate": "2026-04-01T09:30:00Z",
  "lastModifiedByUserDate": "2026-04-01T09:30:00Z",
  "lastSubmittedDate": null,
  "clientLastOpenedDate": null,
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "financialSummary": {
    "partsSubtotal": 8000.00,
    "partsTotal": 8000.00,
    "laborTotal": 2500.00,
    "feeTotal": 0,
    "proposalSubtotal": 10500.00,
    "salesTax": {
      "taxStatus": "Ok",
      "total": 892.50
    },
    "proposalTotal": 11392.50
  },
  "areas": [
    {
      "id": 55,
      "name": "Living Room",
      "options": [
        {
          "id": 201,
          "status": "Draft",
          "lastModifiedDate": "2026-04-01T09:30:00Z",
          "clientDescription": "Standard package",
          "installerDescription": "Use 18-gauge wire throughout",
          "total": 2095.50,
          "totalRecurringService": 0,
          "items": [
            {
              "id": 5001,
              "parentId": null,
              "itemType": "Part",
              "referencedItemId": 88213,
              "createdDate": "2026-03-10T14:05:00Z",
              "lastModifiedDate": "2026-04-01T09:30:00Z",
              "brand": "Sonos",
              "model": "Amp",
              "name": null,
              "shortDescription": "Sonos Amp",
              "clientNote": null,
              "imageUrl": "https://images.portal.io/catalog/sonos-amp.jpg",
              "msrp": 699.00,
              "sellPrice": 649.00,
              "cost": 499.00,
              "costUpdateDate": "2026-04-01T00:00:00Z",
              "supplier": "Sonos Inc.",
              "quantity": 2,
              "total": {
                "amount": 1298.00,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            },
            {
              "id": 5002,
              "parentId": 5001,
              "itemType": "Part",
              "referencedItemId": 90144,
              "createdDate": "2026-03-10T14:06:00Z",
              "lastModifiedDate": "2026-03-10T14:06:00Z",
              "brand": "Sonance",
              "model": "VP62R",
              "name": null,
              "shortDescription": "Sonance VP62R In-Ceiling Speaker",
              "clientNote": null,
              "imageUrl": null,
              "msrp": 179.00,
              "sellPrice": 137.50,
              "cost": 98.00,
              "costUpdateDate": "2026-04-01T00:00:00Z",
              "supplier": "ADI Global Distribution",
              "quantity": 4,
              "total": {
                "amount": 550.00,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            },
            {
              "id": 5003,
              "parentId": null,
              "itemType": "Labor",
              "referencedItemId": 730,
              "createdDate": "2026-03-10T14:08:00Z",
              "lastModifiedDate": "2026-03-10T14:08:00Z",
              "brand": null,
              "model": null,
              "name": "Installation Labor",
              "shortDescription": "Installation Labor",
              "clientNote": null,
              "imageUrl": null,
              "msrp": null,
              "sellPrice": 45.00,
              "cost": null,
              "costUpdateDate": null,
              "supplier": null,
              "quantity": 5.5,
              "total": {
                "amount": 247.50,
                "currency": { "code": "USD", "symbol": "$" },
                "isCombinedPrice": false
              },
              "isTaxExempt": false,
              "isRecurringService": false,
              "linkedOrders": []
            }
          ]
        },
        {
          "id": 202,
          "status": "Draft",
          "lastModifiedDate": "2026-03-28T16:12:00Z",
          "clientDescription": "Premium Installation Package",
          "installerDescription": null,
          "total": 3450.00,
          "totalRecurringService": 25.00,
          "items": []
        }
      ]
    }
  ],
  "changeOrders": [],
  "customer": {
    "id": 88,
    "firstName": "Jane",
    "lastName": "Smith",
    "companyName": "",
    "contactEmail": "jane.smith@example.com"
  },
  "dealer": {
    "id": 5,
    "name": "AV Solutions Inc."
  },
  "coverpageImageUrl": null,
  "aboutUs": "We specialize in smart home integration.",
  "projectDescription": "Whole-home AV and lighting control system.",
  "profit": null,
  "recurringServices": null,
  "paymentSchedule": null,
  "paymentRequests": [],
  "projectTerms": "Payment due within 30 days of completion.",
  "lastModifiedUser": {
    "id": 12,
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}

Authorizations

X-MSS-API-APPID

string

header

required

Portal application identifier used as part of HMAC-authenticated API requests.

X-MSS-API-USERKEY

string

header

required

Portal user API key used together with the HMAC signature headers.

X-MSS-CUSTOM-DATE

string

header

required

Timestamp header included in the signed request to prevent replay attacks.

X-MSS-SIGNATURE

string

header

required

HMAC-SHA256 signature for the request, calculated over the canonical string defined in the authentication docs.

Headers

enum<string>

required

Accept Header

Available options:

application/json

Path Parameters

ProposalId

null | integer<int32>

required

Proposal Id.

Response

Success

Detailed proposal representation

number

integer<int32>

required

Proposal number unique within the dealer account.

name

string

required

Display name of the proposal.

integer<int32>

required

Unique identifier for the proposal. Use this id for subsequent API calls that reference the proposal.

createdDate

string<date-time>

required

UTC timestamp when the proposal was initially created. Returned in ISO 8601 format.

lastModifiedDate

string<date-time>

required

UTC timestamp when the proposal was last modified by any user or system process.

lastModifiedByUserDate

string<date-time>

required

UTC timestamp when the proposal was last modified by a human user (not an automated system update).

status

enum<string>

Available options:

Undefined,

Draft,

Submitted,

ViewedByClient,

Accepted,

Declined,

Delayed,

Completed,

EmailFailed,

Expired

lastSubmittedDate

string<date-time>

UTC timestamp when the proposal was last submitted to the customer.

clientLastOpenedDate

string<date-time>

UTC timestamp when the customer last opened the proposal viewer link.

customer

PublicCustomerModel · object

Customer contact

Show child attributes

dealer

PublicDealerModel · object

Dealer information

Show child attributes

coverpageImageUrl

string

Absolute URL of the proposal cover image, when one is available.

aboutUs

string

The about us text for the company profile.

projectDescription

string

A description of the project.

areas

PublicAreaModel · object[]

The list of areas.

Show child attributes

profit

PublicProfitModel · object

Profit summary for the proposal

Show child attributes

recurringServices

PublicRecurringServicesModel · object

Recurring service summary associated with the proposal.

Show child attributes

paymentSchedule

PublicPaymentScheduleModel · object

Payment schedule configuration for the proposal, including the customer-facing description and individual payment milestones.

Show child attributes

paymentRequests

PublicPaymentRequestModel · object[]

Payment requests already issued for this proposal.

Show child attributes

projectTerms

string

The terms and conditions for the project.

lastModifiedUser

PublicUserModel · object

User summary returned within proposal detail responses

Show child attributes

clientLastDecisionDate

string<date-time>

UTC timestamp when the client last accepted or declined the proposal. Null if no client decision has been recorded.

lastCompletedDate

string<date-time>

UTC timestamp when the proposal last reached a completed state, if applicable.

financialSummary

PublicFinancialSummaryModel · object

Financial totals, discounts, tax, and currency values for the proposal

Show child attributes

changeOrders

PublicChangeOrderModel · object[]

List of change orders associated with this proposal. Each item contains details of scope changes, price adjustments, and approval state.

Show child attributes

⌘I

Authentication

Proposals

Proposal Items

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Authorizations

Headers

Path Parameters

Response