Sending & Signing¶

This covers the full document flow: upload → add recipients → place fields → send → each recipient signs → done. In the app this spans several full-screen steps (Upload, Add Recipients, Prepare Document, the signing Editor) rather than one page, but it's one continuous API sequence — documented here as a single flow with the field-by-field reference for each step.

Overview¶

sequenceDiagram
    participant Owner
    participant API
    participant R1 as Recipient 1
    participant R2 as Recipient 2

    Owner->>API: POST /document/v1 (upload PDF)
    API-->>Owner: { id, workflowId } (draft)
    Owner->>API: POST /workflow/v1/{workflowId}/recipients ([R1, R2])
    Owner->>API: POST /workflow/v1/{documentId}/fields (place signature fields)
    Owner->>API: POST /workflow/v1/{workflowId}/commence

    alt Ordered
        API->>R1: Commence email (R1's turn)
        R1->>API: fields/save + /sign
        API-->>API: Advance sequence
        API->>R2: Commence email (R2's turn)
        R2->>API: fields/save + /sign
        API-->>API: Last recipient done -> seal + completed
    else Unordered
        API->>R1: Commence email
        API->>R2: Commence email
        par Both act independently
            R1->>API: fields/save + /sign
        and
            R2->>API: fields/save + /sign
        end
        API-->>API: Last recipient done -> seal + completed
    end

1. Upload¶

Covered in Documents → Upload. Omitting workflowId creates a new draft workflow; the response gives you both the document id and the workflow id you'll use for every following step.

2. Recipients¶

Endpoint summary¶

Adding recipients¶

POST /workflow/v1/887/recipients
Content-Type: application/json

[
  { "name": "Jane Doe", "emailAddress": "jane@example.com", "useDigitalCert": false, "recipientOrder": "1", "recipientColor": "#4F46E5", "recipientRole": "SIGNER" },
  { "name": "Legal Team", "emailAddress": "legal@example.com", "useDigitalCert": false, "recipientOrder": "2", "recipientColor": "#059669", "recipientRole": "APPROVER" }
]

If an email doesn't match an existing platform user, a guest account is created for them automatically — no separate invite step is needed.

Errors: workflow isn't in draft or isn't owned by the caller; recipients aren't allowed on a self-sign workflow; a Power Survey workflow only accepts SIGNER-role recipients; duplicate order/email under an ordered sequence.

PUT /workflow/v1/{workflowId}/recipients edits existing recipients before sending (same shape + required id). POST .../delegate (below) hands a turn to someone else, usable even after the workflow is sent.

Delegating¶

POST /workflow/v1/887/recipients/5501/delegate
Content-Type: application/json

{ "name": "Backup Signer", "emailAddress": "backup@example.com" }

Usable by the workflow owner or the recipient themself. The delegate inherits the original recipient's order/role/fields.

3. Place fields¶

Endpoint summary¶

POST /workflow/v1/1200/fields
Content-Type: application/json

{ "pageNo": 1, "fieldType": "SIGNATURE", "box": { "x": 100, "y": 200, "width": 150, "height": 40 }, "recipientId": 5501, "fieldRequired": true }

PUT .../fields/{fieldId} additionally supports styling (textColor, fontFamily, bold, italic, underline, strikethrough, textAlign, backgroundColor, fontSize, placeholder, dateLang, useAsLabel).

4. Send¶

POST /workflow/v1/887/commence
Content-Type: application/json

{ "title": "Please review and sign", "message": "See attached NDA for your signature." }

What happens next depends entirely on the sequence:

Responses: 200 OK (normal send completed), 202 Accepted (Power Survey dispatch started), 400 (no recipients, wrong status/owner, or your plan disallows document sharing).

5. Recipient views and signs¶

Each recipient reaches the signing UI via the guest signing flow (or, if already logged in, just their normal session), then:

POST /workflow/v1/1200/fields/save
Content-Type: application/json

[ { "id": 5501, "value": "Jane Doe", "type": "TEXT" } ]

...for each field, followed by:

POST /workflow/v1/887/sign
Content-Type: application/json

{ "id": 5502, "image": "data:image/png;base64,..." }

id is the field id, image the rendered signature/initials image. If the recipient is signing with a digital certificate (useDigitalCert: true) and a password is included in the fields/save call, this is where their signing password is verified — first use provisions their key material, later uses just verify it. This can only happen interactively (never as a background job), since the private key itself is password-protected at the point it was created.

If instead this recipient is an APPROVER: POST /workflow/v1/887/approve with a comment. To reject: POST /workflow/v1/887/decline with a reason — GET /workflow/v1/887/reject-details returns the structured reason afterward.

6. Sequence advances automatically¶

Under ORDERED, the moment one recipient finishes, the next non-CC recipient in order is automatically dispatched — there's no separate "advance" call to make. CC-role recipients are skipped over and simply notified once the sequence reaches their position.

7. Completion¶

Once the last action-required recipient signs or approves, completion happens automatically:

1. The invisible sealing/certification signature is applied.
2. The workflow's status becomes COMPLETED.
3. The evidence report becomes available: GET /workflow/v1/evidence-report/{workflowId} — an HTML audit trail of who signed what, when, from what IP, with what consent record. This is what the app's Audit Report screen renders.

Voided workflows¶

A workflow that's been declined or otherwise voided is read-only from then on — the app's Void screen just displays its final state; there's no separate "void" API action beyond decline (see step 5) or a Power Survey parent cascading a void to its children (see Power Survey).

Two mechanics worth knowing about¶

• Hidden assistant pre-review. If a recipient has Assistant delegation enabled, their turn is transparently routed through their assistant first. This never appears in anyone else's recipient list — from every other participant's perspective, nothing looks different.
• Auto-delegation ("away") swaps. If a recipient has an active auto-delegation window, the platform can silently substitute their stand-in delegate at the moment their turn starts, rather than waiting on someone who's away.

Neither requires any special handling from an integrating client — both are resolved server-side before a commence email is ever sent.

Remote/CSC signing bridge¶

For signers using a remote qualified-signature provider (the CSC protocol) instead of a locally-drawn signature:

GET /workflow/v1/list/user/keys?connectorName=CSC_2

POST /workflow/v1/1200/sign/csc
Content-Type: application/json

{ "id": 5501, "connectorName": "CSC_2", "qualifier": "QES" }

Returns a hash to be signed by the remote provider's own authorization flow; the resulting signature is then submitted:

POST /workflow/v1/1200/signature/csc
Content-Type: application/json

{ "hash": "...", "code": "...", "connectorName": "CSC_2", "qualifier": "QES", "credentialID": "..." }

POST /workflow/v1/signature/csc/batch performs the same exchange across multiple documents in a single authorization step — useful when a signer needs to qualified-sign several documents at once. GET /workflow/v1/check-user-credits/{workflowId}?qualifier=QES and GET /workflow/v1/service-plan-qualifier let the UI pre-check credit/plan eligibility before starting this flow.