What is a Workflow Session?

A Workflow Session is an instance of a workflow. Each time a new customer needs to go through your Workflow, you create a new Workflow Session.

A Workflow Session can only be created from a Workflow Template.
It is created and executed via API.

Create a Workflow Session

Use the POST /workflow_sessions endpoint to create a new Workflow Session.

Rules and recommendations:

You must provide a valid Workflow Template Id.
Every Workflow Session must belong to a Workspace. The rules depend on how the Workflow Template is scoped (the Workflow Template workspace scoping is defined when the template is created).
- Template not scoped to any workspace → You can either specify a Workspace, or leave it empty. In this case, your default workspace will be used.
- Template scoped to a single workspace → You don’t need to provide a Workspace. The Workflow Session will automatically inherit the same Workspace.
- Template scoped to multiple workspaces → You must explicitly choose one of the allowed Workspaces when creating the Workflow Session.
Give your Workflow Session a descriptive name to make it easier to search in the in-app dashboard.
E.g. Onboarding of Kelly Smith, Acme corporation KYB check

Initial state of a Workflow Session

When created, the Workflow Session includes:

All Action Groups from the Workflow Template
Each Action Group in status awaiting
Action Groups are initially empty

As you execute the Workflow Session, Actions are added to each group, and their statuses evolve. See the Understand Workflow Session statuses for details.

Execute a Workflow Session

After creating a Workflow Session, you must execute it via API.

Add Actions (Verifications or Signature Requests) in the order and pace you choose.
Actions populate the relevant Action Groups, and statuses update as they progress.
Yousign does not orchestrate these steps automatically—you define the rules.
- Example: Once the Identity Document Verification status is verified, you can create the Bank Account Verification.

Create Actions in a Workflow Session

In Workflow Sessions, Actions are the existing API resources such as Signature Requests and Verifications (Identity Document Verification, Company Verification, Bank Account Verification, etc.).

To add these Actions to a Workflow Session, you use the same API endpoints as usual (e.g., POST /signature_requests, POST /verifications/identity_documents).

The only difference is that you must include the workflow_session_id in your request body.

This links the Action to the Workflow Session. Yousign then automatically places it in the correct Action Group defined by the Workflow Template.

Available endpoints to create the Actions:

Action group	Endpoints
Bank Account Verification	`POST /verifications/bank_accounts` `POST /verifications/bank_account_connections` `POST /verifications/bank_account_lookups` \|
Identity Verification	`POST /verifications/identity_documents` `POST /verifications/identity_videos`
Company Verification	`POST /verifications/companies`
Watchlist Verification	`POST /verifications/watchlists`
Proof of Address Verification	`POST /verifications/watchlists`
Signature Request	`POST /signature_requests` → After creation, you must add documents, signers, and fields, then activate the request. Learn more here.

Can I add multiple actions in one Action Group?

Yes. For example, if a company has two co-founders and you need to verify both of their bank accounts, you can create two Bank Account Verifications.

The Action Group will only reach status done once all actions inside it are in verified status.

Retrieve Workflow Sessions

To list all Workflow Sessions in your organization, use the GET /workflow_sessions endpoint.
To retrieve a specific Workflow Session by ID, use the GET /workflow_sessions/{workflowSessionId} endpoint.