Concepts & Glossary¶

Most confusion about vScrawl comes from one thing: a "document" in the UI is usually a workflow in the API. This page explains the object model, the status lifecycle, and how UI wording maps to API values.

The object model¶

flowchart TD
    W["<b>Workflow</b><br/>the envelope — what gets sent, tracked, and completed"]
    D1["<b>Document</b><br/>a PDF"]
    D2["<b>Document</b><br/>a PDF"]
    R1["<b>Recipient</b><br/>a person + their role"]
    R2["<b>Recipient</b><br/>a person + their role"]
    F1["<b>Field</b><br/>signature / text / date…"]
    F2["<b>Field</b>"]
    F3["<b>Field</b>"]

    W --> D1
    W --> D2
    W --> R1
    W --> R2
    D1 --> F1
    D1 --> F2
    D2 --> F3
    R1 -.->|assigned to| F1
    R1 -.->|assigned to| F2
    R2 -.->|assigned to| F3

Term	What it actually is
Workflow	The envelope. It owns the recipients, carries the status, and is what "send", "complete", "void", and "decline" act on. Most endpoints take a `workflowId`.
Document	One PDF inside a workflow. A workflow can hold several. Uploading without a `workflowId` creates a new workflow automatically, which is why the upload response returns both ids.
Recipient	A person's participation in one workflow, plus their role and order. Not the same as a user account — the same person on two workflows is two recipient records.
Field	A signature/text/date box placed on a document, assigned to a recipient.
User	An account. Created automatically (as a guest) when you add a recipient whose email doesn't have one yet.

The most common mix-up

A documentId and a workflowId are different numbers, and several endpoints look similar but take different ones — e.g. fields are added under a document (/workflow/v1/{documentId}/fields) while signing happens on the workflow (/workflow/v1/{workflowId}/sign). If a call 404s or acts on the wrong thing, check which id you passed first.

Workflow types¶

Set once at upload via signType, and it determines what's allowed afterwards:

Type	Meaning	Recipients allowed
`SELFSIGN`	You sign your own document. No one else is involved.	None — adding any is rejected
`COUNTERSIGN`	The normal case: send to one or more people.	Any role
`POWERSURVEY`	Bulk send — one document fanned out to many people individually.	`SIGNER` only

There is no separate \"multi-sign\" type

One signer and ten signers are both COUNTERSIGN. What changes is the sequence below — not the type.

Sequence — the ordering rule¶

Set at upload (or changed while still in draft). This is what customers usually mean when they ask "why hasn't the second person received it yet?"

Sequence	Behavior on send
`ORDERED`	One at a time. Only the first recipient is emailed. The next is emailed automatically the moment the previous one finishes.
`UNORDERED`	All at once. Every recipient is emailed immediately and can act in parallel.
`SELF`	Self-sign only.
`SURVEY`	Power Survey fan-out.

If someone reports "recipient 2 never got an email," check the sequence before anything else — under ORDERED that's correct behavior until recipient 1 acts.

Recipient roles¶

Role	Does what
`SIGNER`	Fills fields and signs.
`APPROVER`	Reviews and approves or declines. Does not sign fields.
`CC`	Notified only. Never blocks progress — auto-marked as processed when the sequence reaches them.
`ASSISTANT`	System-assigned, never set by a client. Inserted invisibly when a recipient has assistant delegation turned on, so their assistant pre-reviews first. It doesn't appear in anyone else's recipient list.

Status lifecycle¶

stateDiagram-v2
    [*] --> DRAFT: upload
    DRAFT --> SENT: commence
    SENT --> COMPLETED: last signer/approver acts
    SENT --> APPROVED: approval flow finishes
    SENT --> VOID: declined
    DRAFT --> VOID: declined before sending
    COMPLETED --> [*]
    VOID --> [*]

Status	Meaning
`DRAFT`	Created but not sent. The only state where recipients, fields, and sequence can be edited.
`SENT`	Out for signature. At least one recipient still has an outstanding action.
`COMPLETED`	Everyone required has acted. Sealed, and the evidence report is available.
`APPROVED`	Finished via the approval path.
`VOID`	Declined or cancelled. Terminal and read-only.

Completion is automatic

Nothing needs to call a "finish" endpoint. The moment the last required recipient signs or approves, the workflow seals itself, flips to COMPLETED, and generates its evidence report. If a workflow is stuck in SENT, someone still owes an action — check the recipient list for an unprocessed row.

UI label → API value¶

The app's wording and the API's values don't always match. When a customer quotes what they see on screen, this is the translation:

Customer sees (Documents filter)	Sent to the API as	Maps to a workflow status?
All Documents	(no filter)	—
Draft	`draft`	`DRAFT`
Sent	`sent`	`SENT`
Completed	`completed`	`COMPLETED`
Approved	`approved`	`APPROVED`
Void / Voided	`void`	`VOID`
Pending	`pending`	No
Signed	`signed`	No
Viewed	`viewed`	No

Note the "Completed" pill sends completed, not the complete value used in the URL — that one is translated.

Pending, Signed and Viewed are not workflow statuses

Only five workflow statuses exist (DRAFT, SENT, VOID, COMPLETED, APPROVED). Those three filters describe the state of the item for the person looking at it — whether they've opened it, whether they've already acted — rather than the workflow's own status. Two people can therefore see the same workflow under different filters, and a workflow can appear under "Signed" while its status is still SENT because other recipients haven't finished. That's expected, not a bug.

Several backend states also collapse into one pill on the way in: anything in-progress shows under Sent, and cancelled/expired/rejected/declined all show under Void.

Who can do what¶

Action	Required
Edit recipients / fields / sequence	Workflow is `DRAFT` and you own it
Send (commence)	Workflow owner, valid package, plan allows document sharing
Sign / approve / decline	You are a recipient on it, with the matching role
Delegate a recipient's turn	The workflow owner or that recipient themself
Org settings, members, business apps, email routing	Organization owner
Templates, users, roles, etc.	Granted per custom role

A 403-style error from an organization endpoint is almost always "you're a member, not the owner" rather than a broken token.