Update Proposal Item Image

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/image \
  --header 'Accept: <accept>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-MSS-API-APPID: <api-key>' \
  --header 'X-MSS-API-USERKEY: <api-key>' \
  --header 'X-MSS-CUSTOM-DATE: <api-key>' \
  --header 'X-MSS-SIGNATURE: <api-key>' \
  --form imageUrl=https://images.portal.io/catalog/sonos-amp.jpg \
  --form setDefault=false \
  --form updateAllInstances=false

import requests

url = "https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/image"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"imageUrl\"\r\n\r\nhttps://images.portal.io/catalog/sonos-amp.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"setDefault\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"updateAllInstances\"\r\n\r\nfalse\r\n-----011000010111000001101001--"
headers = {
    "Accept": "<accept>",
    "X-MSS-API-APPID": "<api-key>",
    "X-MSS-API-USERKEY": "<api-key>",
    "X-MSS-CUSTOM-DATE": "<api-key>",
    "X-MSS-SIGNATURE": "<api-key>",
    "Content-Type": "multipart/form-data"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const form = new FormData();
form.append('imageUrl', 'https://images.portal.io/catalog/sonos-amp.jpg');
form.append('setDefault', 'false');
form.append('updateAllInstances', 'false');

const options = {
  method: 'POST',
  headers: {
    Accept: '<accept>',
    'X-MSS-API-APPID': '<api-key>',
    'X-MSS-API-USERKEY': '<api-key>',
    'X-MSS-CUSTOM-DATE': '<api-key>',
    'X-MSS-SIGNATURE': '<api-key>'
  }
};

options.body = form;

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/image', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": 81376,
    "parentId": 42344,
    "itemType": "Part",
    "referencedItemId": 63140,
    "createdDate": "2030-08-21T00:22:19Z",
    "lastModifiedDate": "2031-02-06T00:22:19Z",
    "brand": "Sonos",
    "model": "Amp",
    "name": "Installation Labor",
    "shortDescription": "Sonos Amp",
    "clientNote": "Mounted in the rack behind the display.",
    "imageUrl": "https://images.portal.io/catalog/sonos-amp.jpg",
    "msrp": 901.23,
    "sellPrice": 583.78,
    "cost": 759.6,
    "costUpdateDate": "2030-11-10T00:22:19Z",
    "supplier": "Sonos Inc.",
    "quantity": 9.6,
    "total": {
      "amount": 982.49,
      "currency": {
        "code": "USD",
        "symbol": "$"
      },
      "isCombinedPrice": false
    },
    "isTaxExempt": false,
    "isRecurringService": false,
    "linkedOrders": [
      {
        "orderId": 21802,
        "orderNumber": 182,
        "orderNumberSuffix": "A",
        "supplier": "Sonos Inc.",
        "supplierRef": "SN-10420",
        "orderName": "Living Room Sonos Amp",
        "orderStatus": "Submitted"
      }
    ]
  }
]

{
  "responseStatus": {
    "errorCode": "BadRequest",
    "message": "Neither or both of imageUrl and fileData were supplied, or imageUrl is not an absolute http(s) URL."
  }
}

{
  "responseStatus": {
    "errorCode": "Unauthorized",
    "message": "Not Authorized. Ensure a valid session cookie or HMAC authentication headers are provided."
  }
}

{
  "responseStatus": {
    "errorCode": "PaymentRequired",
    "message": "The dealer's subscription is inactive or expired. An active subscription is required to use this endpoint."
  }
}

{
  "responseStatus": {
    "errorCode": "Forbidden",
    "message": "You do not have permission for this action."
  }
}

{
  "responseStatus": {
    "errorCode": "NotFound",
    "message": "Proposal or item not found."
  }
}

{
  "responseStatus": {
    "errorCode": "Conflict",
    "message": "Proposal state prevents editing"
  }
}

POST

public

proposals

{ProposalId}

items

{ProposalItemId}

image

Update Proposal Item Image

curl --request POST \
  --url https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/image \
  --header 'Accept: <accept>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-MSS-API-APPID: <api-key>' \
  --header 'X-MSS-API-USERKEY: <api-key>' \
  --header 'X-MSS-CUSTOM-DATE: <api-key>' \
  --header 'X-MSS-SIGNATURE: <api-key>' \
  --form imageUrl=https://images.portal.io/catalog/sonos-amp.jpg \
  --form setDefault=false \
  --form updateAllInstances=false

import requests

url = "https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/image"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"imageUrl\"\r\n\r\nhttps://images.portal.io/catalog/sonos-amp.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"setDefault\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"updateAllInstances\"\r\n\r\nfalse\r\n-----011000010111000001101001--"
headers = {
    "Accept": "<accept>",
    "X-MSS-API-APPID": "<api-key>",
    "X-MSS-API-USERKEY": "<api-key>",
    "X-MSS-CUSTOM-DATE": "<api-key>",
    "X-MSS-SIGNATURE": "<api-key>",
    "Content-Type": "multipart/form-data"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const form = new FormData();
form.append('imageUrl', 'https://images.portal.io/catalog/sonos-amp.jpg');
form.append('setDefault', 'false');
form.append('updateAllInstances', 'false');

const options = {
  method: 'POST',
  headers: {
    Accept: '<accept>',
    'X-MSS-API-APPID': '<api-key>',
    'X-MSS-API-USERKEY': '<api-key>',
    'X-MSS-CUSTOM-DATE': '<api-key>',
    'X-MSS-SIGNATURE': '<api-key>'
  }
};

options.body = form;

fetch('https://sandbox.api.portal.io/public/proposals/{ProposalId}/items/{ProposalItemId}/image', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "id": 81376,
    "parentId": 42344,
    "itemType": "Part",
    "referencedItemId": 63140,
    "createdDate": "2030-08-21T00:22:19Z",
    "lastModifiedDate": "2031-02-06T00:22:19Z",
    "brand": "Sonos",
    "model": "Amp",
    "name": "Installation Labor",
    "shortDescription": "Sonos Amp",
    "clientNote": "Mounted in the rack behind the display.",
    "imageUrl": "https://images.portal.io/catalog/sonos-amp.jpg",
    "msrp": 901.23,
    "sellPrice": 583.78,
    "cost": 759.6,
    "costUpdateDate": "2030-11-10T00:22:19Z",
    "supplier": "Sonos Inc.",
    "quantity": 9.6,
    "total": {
      "amount": 982.49,
      "currency": {
        "code": "USD",
        "symbol": "$"
      },
      "isCombinedPrice": false
    },
    "isTaxExempt": false,
    "isRecurringService": false,
    "linkedOrders": [
      {
        "orderId": 21802,
        "orderNumber": 182,
        "orderNumberSuffix": "A",
        "supplier": "Sonos Inc.",
        "supplierRef": "SN-10420",
        "orderName": "Living Room Sonos Amp",
        "orderStatus": "Submitted"
      }
    ]
  }
]

{
  "responseStatus": {
    "errorCode": "BadRequest",
    "message": "Neither or both of imageUrl and fileData were supplied, or imageUrl is not an absolute http(s) URL."
  }
}

{
  "responseStatus": {
    "errorCode": "Unauthorized",
    "message": "Not Authorized. Ensure a valid session cookie or HMAC authentication headers are provided."
  }
}

{
  "responseStatus": {
    "errorCode": "PaymentRequired",
    "message": "The dealer's subscription is inactive or expired. An active subscription is required to use this endpoint."
  }
}

{
  "responseStatus": {
    "errorCode": "Forbidden",
    "message": "You do not have permission for this action."
  }
}

{
  "responseStatus": {
    "errorCode": "NotFound",
    "message": "Proposal or item not found."
  }
}

{
  "responseStatus": {
    "errorCode": "Conflict",
    "message": "Proposal state prevents editing"
  }
}

Sets the image shown for a proposal item. Provide exactly one of ImageUrl or FileData: both, or neither, returns 400.

ImageUrl must be an absolute http or https URL and must be reachable from Portal.io, which downloads and stores a copy. A failed download leaves the item with no image. A relative URL or any other scheme returns 400.
FileData carries the raw bytes, base64-encoded. Animated GIFs are not stored and leave the item without an image.

The response returns imageUrl pointing at the stored copy, not at the source you supplied.

This call also affects proposals other than the one you are editing. Portal.io queues a background job that applies the same image to Part items using the same catalog item across the company’s other draft proposals — only to items that have no image of their own, and never to submitted or accepted proposals. Because it runs asynchronously, those items may take a moment to catch up and never appear in this response.

SetDefault also makes the image the company’s default for the catalog item. Depending on the account’s trust level and how many companies already use the same image, it can become the shared catalog primary image as well. UpdateAllInstances decides what happens to the other instances of this item in the proposal that already have an image — they are overwritten only when it is true. Instances with no image are updated either way.

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

integer<int32>

required

Unique ID of the proposal (not the proposal number).

ProposalItemId

integer<int32>

required

Id of the proposal item to update.

Body

Proposals Service

imageUrl

string

Absolute http(s) URL of the image; any other scheme or a relative URL returns 400. Must be reachable from Portal - a failed download leaves the item without an image. Exactly one of imageUrl and fileData is required.

fileData

array

Raw image bytes, sent base64-encoded. Animated GIFs are not stored and leave the item without an image. Exactly one of imageUrl and fileData is required.

setDefault

boolean

When true, also sets this image as the company's default for the underlying catalog item, so later proposals inherit it. Depending on the account's trust level and how many companies already use the same image, it may also become the shared catalog primary image. Defaults to false.

updateAllInstances

boolean

When true, also overwrites the image of every other instance of the same catalog item in this proposal that already has one. Instances with no image are updated either way. Defaults to false.

Response

Success

integer<int32>

required

Unique numeric identifier of the proposal item

referencedItemId

integer<int32>

required

Identifier of the catalog, labor, custom, or fee item this proposal item was created from

createdDate

string<date-time>

required

UTC timestamp when the proposal item was created

quantity

number<double>

required

Quantity of the proposal item

parentId

integer<int32>

Identifier of the parent item when this item is nested under another item

itemType

enum<string>

Available options:

Part,

Labor,

CustomItem,

Fee

lastModifiedDate

string<date-time>

UTC timestamp when the proposal item was last modified

brand

string

Brand name of the item

model

string

Model value of the item

name

string

Name of a Labor item

shortDescription

string

Short description shown for the proposal item

clientNote

string

Client-facing note for the proposal item

imageUrl

string

Image URL of the item

msrp

number<double>

MSRP amount of the item

sellPrice

number<double>

Sell price for the proposal item

cost

number<double>

Supplier cost for the proposal item

costUpdateDate

string<date-time>

UTC timestamp when the supplier cost was last updated

supplier

string

Display name of the supplier assigned to the item.

total

PublicItemTotalModel · object

Total amount for a proposal item

Show child attributes

isTaxExempt

boolean

Whether the proposal item is tax exempt

isRecurringService

boolean

Whether the proposal item is a recurring service

linkedOrders

PublicLinkedOrderModel · object[]

Linked orders created from this proposal item

Show child attributes

⌘I

Authentication

Proposals

Proposal Items

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Update Proposal Item Image

Authorizations

Headers

Path Parameters

Body

Response