Upsert document image

POST/api/v1/documentImages/upsert

Upsert an image in a named document or template block

Copies an HTTPS image into QuoteCloud storage, replaces one image or gallery cell and verifies the saved assignment. Does not send or change the document status. Sent and read-only documents are refused before import. Empty sourceUrl leaves the image unchanged with a no_source_image warning. Add documentPagePreview and documentPdfLink as separate rendering steps.

Permission

An OAuth access token with this scope. How to get a token

documents:write
Copy, update, and transfer documents and recipients.

Parameters

Not sure what to enter? Here’s where to find IDs.

client_idquery · stringrequired
The Client ID of your OAuth client. It’s public, and goes on every request alongside your access token. Find it in QuoteCloud under Settings → API dashboard → Manage Integrations → OAuth Clients.Length at least 1.

Request body

Sent as application/json.

documentRefstringrequired
Visible company-scoped Document Number
targetstring
Block API Link ID such as customer_logo or cover_render
blockIdstring
Block ID instead of target
cellIdstring
Required for galleries with multiple cells
sourceUrlstring
HTTPS direct-download image URL. Empty or omitted leaves the image unchanged.
fileNamestring
File name with matching image extension. Defaults to image plus the MIME extension.
contentTypestring
Inferred from fileName or URL extension; otherwise image/png. Bytes and response MIME are validated.One of image/png, image/jpeg, image/webp, image/gif.
sourceSystemstring
Provider and account namespace, for example monday:account-123 or sharepoint:tenant-456. Versioned asset identity also includes the target and cellId.
sourceFileIdstring
sourceVersionstring
idempotencyKeystring
Overrides the default documentRef:[sourceSystem:]target:sourceFileId:sourceVersion[:cellId]. Default requires both source fields. Replays within 24 hours retain the stored result with applied false, alreadyApplied true and replayed true; a different request with the same key conflicts. Versioned assets deduplicate by source system, file ID/version and target/cell even with a new request key.Length at most 1000.
layoutobject
Overrides conflicting flat shorthand fields. Omitted fields retain current framing.
Fields
fitstring
Use contain for logos. Cover applies to gallery cells only. A single-image block always renders the whole image and returns a fit_not_applied warning for cover; frame it with focal point and zoom.One of contain, cover.
focalPointobject
Fields
xnumberrequired
Value 0 to 1.
ynumberrequired
Value 0 to 1.
zoomnumber
Value 1 to 3.
altTextstring
Length at most 1000.
altTextstring
Shorthand for layout.altTextLength at most 1000.
fitstring
Use contain for logos. Cover applies to gallery cells only; single-image blocks render the whole image with a fit_not_applied warning. Frame with focal point and zoom.One of contain, cover.
focalPointXnumber
Shorthand. The other coordinate defaults to 0.5 when omitted.Value 0 to 1.
focalPointYnumber
Value 0 to 1.
zoomnumber
Value 1 to 3.

Needs one of target, blockId.

Responses

200Applied, already applied, or empty-source no-op. Verification checks stored block data; rendering is a separate operation.
dataobjectrequired
Fields
statusstringrequired
One of success.
successbooleanrequired
appliedbooleanrequired
alreadyAppliedbooleanrequired
replayedboolean
True when returning a cached idempotent result
documentRefstringrequired
documentIdstringrequired
blockIdstring
blockLinkIdstring or null
cellIdstring
assetIdstring
revisionTokenstring
imageobject
Fields
cellIdstringrequired
assetIdstring or nullrequired
fitstringrequired
One of contain, cover, fill, none, scale-down.
fitIsDefaultbooleanrequired
focalPointobjectrequired
Fields
xnumber
Value 0 to 1.
ynumber
Value 0 to 1.
zoomnumberrequired
Value 1 to 3.
altTextstring or nullrequired
dataItemstring or nullrequired
previousImageobject
Fields
cellIdstringrequired
assetIdstring or nullrequired
fitstringrequired
One of contain, cover, fill, none, scale-down.
fitIsDefaultbooleanrequired
focalPointobjectrequired
Fields
xnumber
Value 0 to 1.
ynumber
Value 0 to 1.
zoomnumberrequired
Value 1 to 3.
altTextstring or nullrequired
dataItemstring or nullrequired
pdfInvalidatedboolean
retryableboolean
verifiedobject
Fields
blockboolean
readbackobject
Shared block-image read-back including cells and attachment metadata
warningsarray of objectrequired
Item fields
codestring
messagestring
nextStepsobject
Fields
generatePdfstring
pagePreviewstring
400Invalid request or validation failure.
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired
401Missing or invalid bearer token or client ID.
errorstringrequired
error_descriptionstring
403Insufficient scope, missing add-on, usage limit, or permission denial.

Exactly one of these:

OAuthError
errorstringrequired
error_descriptionstring
ApiErrorEnvelope
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired
404Requested resource was not found in the token's company.
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired
409Read-only, idempotency reuse, or revision/verification conflict. retryable is false for read-only and key reuse; true for a second revision conflict.

No response body.

415Unsupported image MIME type. retryable is false.

No response body.

423Edit lease or element lock busy. retryable is true.

No response body.

429Shared company API request quota exceeded. Wait before retrying.
Retry-Afterheader · integer
Minimum seconds to wait before retrying.Value at least 1.
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
retryAfterSecondsintegerrequired
Value at least 1.
500Unexpected server error.
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired
502Download or storage failure. retryable is true.

No response body.

504Image download timeout. retryable is true.

No response body.

Rate limit

120 requests a minute per company, shared across REST, Zapier and MCP. On a 429, wait for Retry-After.