Create a New Proposal

curl -i -X POST \
  'https://sandbox.api.portal.io/public/proposals' \
  -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 'SalesPersonId=42' \
  -d 'Name=Smith+Residence+AV'

import requests
from portal_auth import sign_request

url = "https://sandbox.api.portal.io/public/proposals"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
content_type = "application/x-www-form-urlencoded"
signature = sign_request("POST", url, content_type, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.post(url, headers={
    "Accept": "application/json",
    "Content-Type": content_type,
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
}, data={
    "SalesPersonId": "42",
    "Name": "Smith Residence AV"
})
print(response.json())

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

const url = "https://sandbox.api.portal.io/public/proposals";
const timestamp = new Date().toUTCString();
const contentType = "application/x-www-form-urlencoded";
const signature = signRequest("POST", url, contentType, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": contentType,
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    },
    body: new URLSearchParams({ SalesPersonId: "42", Name: "Smith Residence AV" })
});
const data = await response.json();
console.log(data);

{
  "id": 1042,
  "number": 1005,
  "name": "Smith Residence AV",
  "status": "Draft",
  "createdDate": "2026-04-06T00:22:19Z",
  "lastModifiedDate": "2026-04-06T00:22:19Z",
  "lastModifiedByUserDate": "2026-04-06T00:22:19Z",
  "lastSubmittedDate": null,
  "clientLastOpenedDate": null,
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "financialSummary": {
    "partsSubtotal": 0,
    "partsTotal": 0,
    "laborTotal": 0,
    "feeTotal": 0,
    "proposalSubtotal": 0,
    "salesTax": {
      "taxStatus": "Undefined",
      "total": 0
    },
    "proposalTotal": 0
  },
  "areas": [],
  "changeOrders": [],
  "customer": null,
  "dealer": {
    "id": 5,
    "name": "AV Solutions Inc."
  },
  "coverpageImageUrl": null,
  "aboutUs": null,
  "projectDescription": null,
  "profit": null,
  "recurringServices": null,
  "paymentSchedule": null,
  "paymentRequests": [],
  "projectTerms": null,
  "lastModifiedUser": {
    "id": 42,
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}

POST

public

proposals

curl -i -X POST \
  'https://sandbox.api.portal.io/public/proposals' \
  -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 'SalesPersonId=42' \
  -d 'Name=Smith+Residence+AV'

import requests
from portal_auth import sign_request

url = "https://sandbox.api.portal.io/public/proposals"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
content_type = "application/x-www-form-urlencoded"
signature = sign_request("POST", url, content_type, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.post(url, headers={
    "Accept": "application/json",
    "Content-Type": content_type,
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
}, data={
    "SalesPersonId": "42",
    "Name": "Smith Residence AV"
})
print(response.json())

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

const url = "https://sandbox.api.portal.io/public/proposals";
const timestamp = new Date().toUTCString();
const contentType = "application/x-www-form-urlencoded";
const signature = signRequest("POST", url, contentType, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": contentType,
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    },
    body: new URLSearchParams({ SalesPersonId: "42", Name: "Smith Residence AV" })
});
const data = await response.json();
console.log(data);

{
  "id": 1042,
  "number": 1005,
  "name": "Smith Residence AV",
  "status": "Draft",
  "createdDate": "2026-04-06T00:22:19Z",
  "lastModifiedDate": "2026-04-06T00:22:19Z",
  "lastModifiedByUserDate": "2026-04-06T00:22:19Z",
  "lastSubmittedDate": null,
  "clientLastOpenedDate": null,
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "financialSummary": {
    "partsSubtotal": 0,
    "partsTotal": 0,
    "laborTotal": 0,
    "feeTotal": 0,
    "proposalSubtotal": 0,
    "salesTax": {
      "taxStatus": "Undefined",
      "total": 0
    },
    "proposalTotal": 0
  },
  "areas": [],
  "changeOrders": [],
  "customer": null,
  "dealer": {
    "id": 5,
    "name": "AV Solutions Inc."
  },
  "coverpageImageUrl": null,
  "aboutUs": null,
  "projectDescription": null,
  "profit": null,
  "recurringServices": null,
  "paymentSchedule": null,
  "paymentRequests": [],
  "projectTerms": null,
  "lastModifiedUser": {
    "id": 42,
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}

Creates a new proposal under the authenticated account. You must supply the ID of a salesperson (user) who belongs to the same account. If no name is provided, the system assigns a default name using the same naming logic as the Portal.io UI. The response returns the complete proposal detail object, including the new proposal’s ID, number, status, and financial summary.

curl -i -X POST \
  'https://sandbox.api.portal.io/public/proposals' \
  -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 'SalesPersonId=42' \
  -d 'Name=Smith+Residence+AV'

import requests
from portal_auth import sign_request

url = "https://sandbox.api.portal.io/public/proposals"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
content_type = "application/x-www-form-urlencoded"
signature = sign_request("POST", url, content_type, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.post(url, headers={
    "Accept": "application/json",
    "Content-Type": content_type,
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
}, data={
    "SalesPersonId": "42",
    "Name": "Smith Residence AV"
})
print(response.json())

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

const url = "https://sandbox.api.portal.io/public/proposals";
const timestamp = new Date().toUTCString();
const contentType = "application/x-www-form-urlencoded";
const signature = signRequest("POST", url, contentType, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": contentType,
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    },
    body: new URLSearchParams({ SalesPersonId: "42", Name: "Smith Residence AV" })
});
const data = await response.json();
console.log(data);

{
  "id": 1042,
  "number": 1005,
  "name": "Smith Residence AV",
  "status": "Draft",
  "createdDate": "2026-04-06T00:22:19Z",
  "lastModifiedDate": "2026-04-06T00:22:19Z",
  "lastModifiedByUserDate": "2026-04-06T00:22:19Z",
  "lastSubmittedDate": null,
  "clientLastOpenedDate": null,
  "clientLastDecisionDate": null,
  "lastCompletedDate": null,
  "financialSummary": {
    "partsSubtotal": 0,
    "partsTotal": 0,
    "laborTotal": 0,
    "feeTotal": 0,
    "proposalSubtotal": 0,
    "salesTax": {
      "taxStatus": "Undefined",
      "total": 0
    },
    "proposalTotal": 0
  },
  "areas": [],
  "changeOrders": [],
  "customer": null,
  "dealer": {
    "id": 5,
    "name": "AV Solutions Inc."
  },
  "coverpageImageUrl": null,
  "aboutUs": null,
  "projectDescription": null,
  "profit": null,
  "recurringServices": null,
  "paymentSchedule": null,
  "paymentRequests": [],
  "projectTerms": null,
  "lastModifiedUser": {
    "id": 42,
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}

Headers

enum<string>

required

Accept Header

Available options:

application/json

X-MSS-API-APPID

string

required

Application Id

X-MSS-CUSTOM-DATE

string

required

A date timestamp of the request

X-MSS-SIGNATURE

string

required

A signature for the request

X-MSS-API-USERKEY

string

required

User API Key

Body

application/x-www-form-urlencoded

SalesPersonId

integer<int32>

required

ID of the salesperson (user) who will own the proposal. Must belong to the current account.

Name

string

Optional name of the proposal. If omitted, the system will assign a default name.

Response

Success

Detailed proposal representation

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).

financialSummary

PublicFinancialSummaryModel · object

required

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

Show child attributes

number

integer<int32>

required

Proposal number unique within the dealer account.

name

string

required

Display name of the proposal.

status

enum<string>

required

The current status of the resource.

Available options:

Undefined,

Draft,

Submitted,

ViewedByClient,

Accepted,

Declined,

Delayed,

Completed,

EmailFailed,

Expired

dealer

PublicDealerModel · object

required

Dealer information

Show child attributes

lastModifiedUser

PublicUserModel · object

required

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.

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

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

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.

List and Search Proposals

Get Proposal Details

⌘I

Authentication

Proposals

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Headers

Body

Response