Documents¶

Upload, list, filter, download, and manage documents.

Endpoint summary¶

Method	Path	Summary
POST	`/document/v1` (multipart)	Upload a document
GET	`/document/v1/cloud-import/dropbox`	Proxy a file picked in the Dropbox Chooser (see Cloud Source import)
PUT	`/document/v1/{docId}` (multipart)	Replace a document's file
PUT	`/document/v1/{docId}` (JSON)	Rename a document
PUT	`/document/v1/sequence/{workflowId}`	Set signing order mode
GET	`/document/v1`	List documents (paginated, filterable)
GET	`/document/v1/{docId}`	Get one document
GET	`/document/v1/docs-detail/{workflowId}`	Get all documents attached to one workflow
GET	`/document/v1/count/documents-status`	Counts by status (feeds the status-filter pills)
GET	`/document/v1/download/{workflowId}`	Download signed document(s) / certificate of completion
DELETE	`/document/v1`, `/{workflowId}`, `/workflows`	Delete document(s)
PUT	`/document/v1/{workflowId}/change-sequence`	Reorder documents within a workflow
PUT	`/workflow/v1/rename/{workflowId}`	Rename the workflow (envelope)
GET	`/workflow/v1/sequence/{workflowId}`	Is this workflow ordered?
PUT	`/workflow/v1/{workflowId}`	Change the signing-order mode
PUT	`/workflow/v1/{workflowId}/reminder`	Configure automatic recipient reminders
GET	`/workflow/v1/{workflowId}/history`	Audit trail for the workflow

Upload¶

POST /document/v1?sequence=UNORDERED&signType=COUNTERSIGN
Content-Type: multipart/form-data

file: <binary PDF>

Query param	Type	Notes
`workflowId`	long, optional	Attach to an existing draft workflow instead of creating a new one
`sequence`	string, optional	`SELF`, `ORDERED`, `UNORDERED`, `SURVEY` — only meaningful when creating a new one
`signType`	string, optional	`SELFSIGN`, `COUNTERSIGN`, `POWERSURVEY`
`folderId`	long, optional	Target folder — see Folders
`timeZone`	string, optional	Recipient-facing display timezone

Accepted formats: .pdf, .doc, .docx — Word files are converted to PDF server-side on upload. Max 25 MB.

Success (201 Created):

{ "id": 1200, "workflowId": 887, "thumbnailBase64": "iVBORw0KGgoAAAANSUhEUgAA..." }

Rejections:

Condition	Error
Extension other than pdf/doc/docx	`INVALID_DOCUMENT_TYPE`
Empty file	`INVALID_DOCUMENT_SIZE`
PDF already carrying a signature	`DOCUMENT_ALREADY_SIGNED`

PUT /document/v1/{docId} (multipart) replaces the file — only while still in draft and owned by the caller. Replacement accepts PDF only, unlike the initial upload which also takes Word files. A separate JSON-body PUT /document/v1/{docId} ({ "name": "..." }, 1-50 chars) renames it.

This is step 1 of the full send flow — continue with Sending & Signing to add recipients, place fields, and send.

Cloud Source import¶

A signer can bring a document in from their own Google Drive or Dropbox instead of picking a local file. This is entirely optional per organization — it is gated by the organization's service plan, and the plan also decides which Google Cloud project / Dropbox app is used, since more than one can exist on an installation.

Availability is not a separate call. Three fields on GET /user/v1/settings/profile tell the client what to offer:

{
  "googleDriveClientId": "123456789-abc.apps.googleusercontent.com",
  "googleDriveApiKey": "AIzaSyD...",
  "dropboxAppKey": "a1b2c3d4e5f6g7h"
}

All three are null when the organization's plan does not grant that provider. Treat Google Drive as available only when both googleDriveClientId and googleDriveApiKey are non-null — the Picker cannot open with just one, and the two always arrive together or not at all.

Google Drive — no extra endpoint¶

The whole flow is client-side, against Google directly, using the Google Picker / Identity Services libraries with the two values above:

Open an OAuth consent popup for the drive.file scope, restricted to files the user explicitly picks.
Load the Picker with the returned access token and googleDriveApiKey.
On selection, download the file directly from the Google Drive API (which answers cross-origin), in the browser.
Upload it through the ordinary POST /document/v1 above, exactly like a local file.

No vScrawl endpoint is involved until step 4.

Dropbox — one extra endpoint¶

The Dropbox Chooser is a client-side popup keyed by dropboxAppKey, same idea. The difference is what it hands back: a temporary link rather than the file's bytes, on a host that does not reliably answer a cross-origin browser fetch. The client resolves it through this service instead:

GET /document/v1/cloud-import/dropbox?link=https%3A%2F%2Fuc1234.dl.dropboxusercontent.com%2Fcd%2F...

Returns the raw bytes (application/octet-stream). The link is validated against an allow-list of Dropbox hosts — checked again after every redirect, so this cannot be used to fetch an arbitrary URL — and the response is capped at 25 MB, the same ceiling POST /document/v1 enforces. The client wraps the bytes in a file and uploads them through the same upload call.

Condition	Response
`link` is not a url, not `https`, or not on an allowed Dropbox host (including after a redirect)	`400`
The link could not be read, redirected more than 5 times, or exceeded 25 MB	`500`

Listing and filtering¶

`GET /document/v1`¶

Paginated (see Pagination), filters: status, folderID, searchValue.

{
  "content": [
    {
      "workflowId": 887,
      "documentCount": 1,
      "recipientCount": 2,
      "name": "NDA - Acme Corp",
      "ownerName": "Jane Doe",
      "status": "SENT",
      "anyDigitalSignature": true,
      "isPowerSurvey": false,
      "isPowerSurveyChild": false
    }
  ],
  "totalElements": 42
}

When the caller is a recipient rather than the owner, recipientId/recipientRole/enforceIdentity are populated for their own row.

Status-filter pills

The Documents page's filter pills (All, Signed, Sent, Pending, Draft, Completed, Approved, Viewed, Void) work off this same list, passing the pill's value as status. Draft/Sent/Completed/Approved/Void map to the workflow's own status; Signed, Pending, and Viewed are not workflow statuses — see Concepts for what they actually reflect.

`GET /document/v1/{docId}`, `GET /document/v1/docs-detail/{workflowId}`¶

Single-document and all-documents-for-a-workflow detail views — same shape as the list item above plus size, pages, isViewed.

`GET /document/v1/count/documents-status`¶

{ "draftDocCount": 3, "pendingDocCount": 5, "sentDocCount": 12, "signedDocCount": 8, "completedDocCount": 40, "voidDocCount": 2 }

Downloading¶

GET /document/v1/download/887?selectedOption=downloadDocument&documentId=1200

selectedOption (required): downloadDocument (one document), downloadAll (all documents in the workflow, zipped), downloadCoc (certificate of completion / evidence report as PDF). documentId required only for downloadDocument.

Deleting and reordering¶

DELETE /document/v1 (body: { "ids": [1, 2] }), DELETE /document/v1/{workflowId}, and DELETE /document/v1/workflows (body: { "workflowIds": "1,2,3" }) cover single/bulk deletion at different granularities. PUT /document/v1/{workflowId}/change-sequence reorders multiple documents attached to one workflow (body: [{ "documentId": 1200, "order": 1 }, ...]).

Renaming the workflow¶

Renaming a document is PUT /document/v1/{docId} with JSON. Renaming the workflow — the envelope the documents sit in, which is the name recipients see — is a different call:

PUT /workflow/v1/rename/887
Content-Type: application/json

{ "name": "Supplier agreement 2026" }

name is required and must be 1–50 characters. Only the workflow owner may rename it.

Signing order¶

The order mode lives on the workflow, not on the documents.

GET /workflow/v1/sequence/887

Returns a bare true or false — true when the workflow is ORDERED, meaning recipients act one at a time in sequence. To change the mode:

PUT /workflow/v1/887
Content-Type: application/json

{ "sequence": "ORDERED" }

Value	Meaning
`SELF`	Self-sign — the owner is the only signer
`ORDERED`	Recipients act one after another, in the order they were added
`UNORDERED`	Everyone can act at once
`SURVEY`	Power Survey bulk send

PUT /document/v1/sequence/{workflowId} sets the same mode through the document service; both routes exist and change the same workflow field.

Automatic reminders¶

Reminders chase recipients who have not acted yet. Configure them while the workflow is still a draft — the call is rejected once it has been sent.

PUT /workflow/v1/887/reminder
Content-Type: application/json

{ "enabled": true, "intervalDays": 3 }

Field	Notes
`enabled`	`false` turns reminders off and clears the schedule
`intervalDays`	Whole-days mode: 1–30. Fires this many days after the recipient's turn begins
`offsetMinutes`	Sub-day mode: 1–1439. Fires this many minutes after the recipient receives the document

Send one of intervalDays or offsetMinutes. If offsetMinutes is present it wins and intervalDays is ignored; if neither is valid the call fails with BAD_REQUEST_BODY.

Two rules are enforced server-side and are worth knowing before you build against this:

Owner only. Anyone else gets INVALID_WORKFLOW_OWNER.
Draft only. A workflow that has already been sent returns INVALID_WORKFLOW_STATUS.
Self-sign workflows never get reminders. The owner is the only signer, so enabled is forced to false whatever the request says — with no error.