CloudPDF
DocsPricing
Start building

Prepare a signature

POST/v1/docs/{docId}/layers/{layerName}/signatures/preparev3.0.0-next.15

Author and seal a signing candidate; returns the digest to sign and the version fences.

Multipart: a JSON `body` part (field, subFilter, digest, contentsSize, signer, certify, lock), naming the appearance PDF it may carry as `resources: { appearance: '<key>' }`, and that PDF as the part `resource:<key>`. A certification (`certify.permission`) additionally requires `doc.sign.certify`. The layer is read-only until the signing completes, is cancelled, or expires (15 minutes). A layer behind the document head cannot sign (StaleBase).

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

Parameters#

docIdpathstringrequired
layerNamepathstringrequired
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.

Request body#

multipart/form-dataobjectrequired
filestring<binary>required

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.signatures.prepare({
  file: fs.createReadStream("/path/to/your/file"),
  docId: "docId",
  layerName: "layerName"
});

Responses#

200OK
application/jsonDocSignaturesPrepare200Response
signingIdstring
digeststring
algorithm"sha256" | "sha384" | "sha512"
byteRange[integer, integer, integer, integer]
contentsSizeinteger
subFilterstring
expectedVersionobject
baseSha256string
editsVersioninteger
expiresAtstring
400Bad request
application/jsonDocSignaturesPrepare400Response
404Not found
application/jsonDocSignaturesPrepare404Response
409Conflict
application/jsonDocSignaturesPrepare409Response
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