Power Survey (Bulk Send)¶

Send one document to many recipients at once, each getting their own independent copy to sign, with aggregate progress tracked from a single monitoring screen.

What a Power Survey actually is¶

One parent workflow holds the master document and the target recipient list. On send, it fans out into N independent child workflows — one per recipient, each with its own copy of the document and its own single signer. The parent itself is never signed directly; it only tracks and aggregates. This is the screen behind the app's power-survey monitoring page, opened whenever a dispatched survey is clicked from Documents.

sequenceDiagram
    participant Owner
    participant API
    participant Dispatch as Async Dispatch

    Owner->>API: POST /document/v1 (upload, signType=POWERSURVEY)
    Owner->>API: POST /workflow/v1/{parentId}/recipients ([500 signers])
    Owner->>API: POST /workflow/v1/{parentId}/commence
    API-->>Owner: 202 Accepted (dispatch started)
    API->>Dispatch: dispatch each recipient

    loop For each recipient
        Dispatch->>Dispatch: Create child workflow
        Dispatch->>Dispatch: Copy document + fields
        Dispatch->>Dispatch: Send it (email)
    end
    Dispatch-->>API: Parent flipped to sent

    Owner->>API: GET /power-survey/{parentId}/dispatch-progress (poll)
    Note over Owner,API: ...time passes, children get signed independently...
    Owner->>API: GET /power-survey/{parentId}/workflows
    Owner->>API: GET /power-survey/{parentId}/export.csv

1. Author the survey¶

Same as a normal upload, with signType=POWERSURVEY:

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

file: <binary PDF>

Constraints enforced at dispatch time (worth knowing up front, not just when the error shows up):

• Exactly one document.
• Exactly one un-assigned signature field on that document — every recipient signs the same spot.
• Every other field must have a label set.
• Recipient count must be under your plan's configured survey recipient limit.

2. Add recipients¶

POST /workflow/v1/{parentWorkflowId}/recipients
Content-Type: application/json

[
  { "name": "John Smith", "emailAddress": "john@example.com", "useDigitalCert": false, "recipientColor": "#4F46E5", "recipientRole": "SIGNER" }
]

Only SIGNER-role recipients are allowed on a Power Survey parent. Same field reference as Sending & Signing → Recipients.

3. Trigger the fan-out¶

Exactly the same call as a normal send:

POST /workflow/v1/{parentWorkflowId}/commence
Content-Type: application/json

{ "title": "Quick survey", "message": "Please review and sign." }

Because the parent is a Power Survey, this returns 202 Accepted immediately and hands off to background dispatch rather than completing synchronously. Calling it again while dispatch is still in progress is a safe no-op — it won't create duplicate children.

4. Poll progress¶

Lightweight poll¶

GET /document/v1/power-survey/{parentWorkflowId}/dispatch-progress

{ "dispatchedCount": 340, "totalRecipients": 500 }

Full status¶

GET /document/v1/power-survey/{parentWorkflowId}/workflows?page=0&size=50

{
  "content": [
    { "workflowId": 9001, "recipientName": "John Smith", "recipientEmail": "john@example.com", "status": "COMPLETED" }
  ],
  "totalElements": 500,
  "completedCount": 210,
  "respondedCount": 225,
  "dispatchedCount": 500
}

respondedCount counts completed and voided/declined children; completedCount counts only fully-signed ones. These aggregates describe the whole survey, not just the current page.

5. Each recipient signs independently¶

Every child workflow goes through the exact same Sending & Signing flow as a standalone one-recipient envelope, including Guest Signing for recipients without accounts. There's nothing survey-specific about how any one recipient signs.

6. Parent status rolls up automatically¶

7. Export results¶

GET /document/v1/power-survey/{parentWorkflowId}/export.csv?includeFields=true

Streams a CSV of every recipient's outcome. includeFields=true adds each recipient's filled field values as extra columns.

Cancelling a survey¶

Declining the parent cascades: every still-pending child is voided. Already-completed children are untouched.