CloudPDF
DocsPricing
Start building

Update form widget

PATCH/v1/docs/{docId}/layers/{layerName}/form/widgets/{pageKey}/{annotKey}v3.0.0-next.15

Change a widget's place and look: what an annotation update takes, for a form field's widget. A widget is the form's, so the annotation routes refuse one.

Authentication#

Any one of these credentials is accepted.

API token

The deployment's static root credential (CLOUDPDF_API_AUTH_TOKENS), valid on every surface.

Document token

Doc-scoped JWT, valid only on the /v1/docs/{docId} subtree it names, gated by the capability scopes it carries (each operation's x-required-capability).

Document capabilitydoc.forms.modify

Parameters#

docIdpathstringrequired
layerNamepathstringrequired
pageKeypathstringrequired
annotKeypathstringrequired
X-Document-Passwordheaderstring

Base64-encoded password for an encrypted document. Valid only with the API token (403 anywhere else). An encrypted document answers 422 DocPasswordRequired when the header is absent. Viewer doc JWTs use the SDK password-session flow instead.

Idempotency-Keyheaderstring

Names the change: 1 to 255 printable ASCII characters. A retry under the same key on the same layer answers with what the first request committed, and changes nothing.

Request body#

application/jsonDocFormsUpdateWidgetRequestrequired
patchWidgetPatchrequired
subtype"widget"
refunknown
pageunknown
hasAppearanceunknown
appearanceStateunknown
nmstring
rectobject
xnumberrequired
ynumberrequired
widthnumberrequired
heightnumberrequired
contentsstring
subjectstring
blendMode"normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity"
invisibleboolean
hiddenboolean
printboolean
noZoomboolean
noRotateboolean
noViewboolean
readOnlyboolean
lockedboolean
toggleNoViewboolean
lockedContentsboolean
replyobject
toAnnotationRefrequired
kind =
kind"objectNumber"required
pagePageRefrequired
objectNumberintegerrequired
type"reply" | "group"
popupunknown
groupIdstring
authorunknown
createdAtunknown
modifiedAtunknown
userIdunknown
createdByunknown
modifiedByunknown
importedByunknown
actionsWidgetActionsPatch | PdfAnnotationActions
boxobject
xnumberrequired
ynumberrequired
widthnumberrequired
heightnumberrequired
rotation0 | 90 | 180 | 270
colorstring
interiorColorstring
strokeWidthnumber
borderStyle"solid" | "dashed" | "beveled" | "inset" | "underline"
dashArraynumber[]
fontFamilystring
fontSizenumber
fontColorstring
textAlign"left" | "center" | "right"
captionstring
checkStyle"check" | "cross" | "star" | "circle" | "square" | "diamond"
fieldunknown
fieldFamilyunknown

A complete body with every required field. Strings stand in for your own values.

{
  "patch": {
    "subtype": "widget",
    "ref": null,
    "page": null,
    "hasAppearance": null,
    "appearanceState": null,
    "nm": "nm",
    "rect": {
      "x": 1,
      "y": 1,
      "width": 1,
      "height": 1
    },
    "contents": "contents",
    "subject": "subject",
    "blendMode": "normal",
    "invisible": true,
    "hidden": true,
    "print": true,
    "noZoom": true,
    "noRotate": true,
    "noView": true,
    "readOnly": true,
    "locked": true,
    "toggleNoView": true,
    "lockedContents": true,
    "reply": {
      "to": {
        "kind": "objectNumber",
        "page": {
          "kind": "objectNumber",
          "objectNumber": 1
        },
        "objectNumber": 1
      }
    },
    "popup": null,
    "groupId": "groupId",
    "author": null,
    "createdAt": null,
    "modifiedAt": null,
    "userId": null,
    "createdBy": null,
    "modifiedBy": null,
    "importedBy": null,
    "actions": null,
    "box": {
      "x": 1,
      "y": 1,
      "width": 1,
      "height": 1
    },
    "rotation": 0,
    "color": "color",
    "interiorColor": null,
    "strokeWidth": 1,
    "borderStyle": "solid",
    "dashArray": [
      1
    ],
    "fontFamily": "fontFamily",
    "fontSize": 1,
    "fontColor": null,
    "textAlign": "left",
    "caption": "caption",
    "checkStyle": "check",
    "field": null,
    "fieldFamily": null
  }
}

SDK examples#

The selected SDK is remembered across the API reference. Values are examples; replace them with identifiers and input from your application.

import { CloudPDFClient } from "@cloudpdf/sdk";

const client = new CloudPDFClient({
  baseUrl: "https://yourhost.com/path/to/api",
  token: "<token>",
});

await client.doc.forms.updateWidget({
  docId: "docId",
  layerName: "layerName",
  pageKey: "pageKey",
  annotKey: "annotKey",
  patch: {}
});

Responses#

200OK
application/jsonDocFormsUpdateWidget200Response
widgetWidgetAnnotation
subtype"widget"
refAnnotationRef
kind =
kind"objectNumber"
pagePageRef
kind"objectNumber"
objectNumberinteger
objectNumberinteger
pagePageRef
kind"objectNumber"
objectNumberinteger
hasAppearanceboolean
appearanceStatestring
nmstring
rectobject
xnumber
ynumber
widthnumber
heightnumber
contentsstring
subjectstring
blendMode"normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity"
invisibleboolean
hiddenboolean
printboolean
noZoomboolean
noRotateboolean
noViewboolean
readOnlyboolean
lockedboolean
toggleNoViewboolean
lockedContentsboolean
replyobject
toAnnotationRef
kind =
kind"objectNumber"
pagePageRef
objectNumberinteger
type"reply" | "group"
popupAnnotationRef
groupIdstring
authorstring
createdAtstring<date-time>
modifiedAtstring<date-time>
userIdstring
createdBystring
modifiedBystring
importedBystring
actionsPdfAnnotationActions
boxobject
xnumber
ynumber
widthnumber
heightnumber
rotation0 | 90 | 180 | 270
colorstring
interiorColorstring
strokeWidthnumber
borderStyle"solid" | "dashed" | "beveled" | "inset" | "underline"
dashArraynumber[]
fontFamilystring
fontSizenumber
fontColorstring
textAlign"left" | "center" | "right"
captionstring
checkStyle"check" | "cross" | "star" | "circle" | "square" | "diamond"
fieldFormFieldRef
fieldFamily"text" | "checkbox" | "radio" | "combobox" | "listbox" | "pushbutton" | "signature" | "unknown"
appearanceobject
action"preserved" | "regenerated" | "generation-unavailable" | "restored"
changedboolean
metaFormMutationMeta
affectedPagesPageRef[]
kind"objectNumber"
objectNumberinteger
cacheDeltaCacheDelta
opIdstring
undoableboolean
changedFieldsFormFieldRef[]
kind =
kind"objectNumber"
objectNumberinteger
changedWidgetsFormWidget[]
refAnnotationRef
objectNumberinteger
pagePageRef
redrawnWidgetsFormWidget[]
refAnnotationRef
objectNumberinteger
pagePageRef
400Bad request
application/jsonDocFormsUpdateWidget400Response
404Not found
application/jsonDocFormsUpdateWidget404Response
defaultError
application/jsonEngineErrorPayload
name"EngineError"
code"Unknown" | "InvalidArg" | "DocNotOpen" | "DocOpenFailed" | "DocPasswordRequired" | "DocPasswordIncorrect" | "SharePasswordRequired" | "Aborted" | "Network" | "Unauthenticated" | "Forbidden" | "NotFound" | "WireFormat" | "RuntimeUnavailable" | "LayerVersionConflict" | "NotImplemented" | "MalformedPdf" | "SigningPending" | "SigningExpired" | "SigningVersionMismatch" | "SignatureRefused" | "ProtectedDocument" | "StaleBase" | "PayloadTooLarge" | "ObjectNumberUnavailable" | "LayerFull" | "ChangeConflict" | "UndoUnavailable" | "IdempotencyKeyReused"
messagestring
detailsobjectoptional