# Workflow Guide

This guide explains how the NSE API is structured and how you can combine its building blocks to model a wide range of real-world signing scenarios. Rather than walking through individual API calls, it focuses on the concepts behind the API and the different workflow patterns you can build.

## The Building Blocks

Every signing workflow in NSE is built from four objects that nest inside each other:

```
Envelope
  └── Stage 1
  │     ├── Recipient A
  │     └── Recipient B
  └── Stage 2
        └── Recipient C
  └── File (Document)
        └── Field Tasks  (linked to specific recipients)
```

**Envelope** — the top-level container. It holds everything: documents, stages, and their recipients. An envelope moves through a lifecycle (draft → sent → completed) and is the object you track and download from.

**Stage** — a step in the signing workflow. Stages execute sequentially: stage 2 does not start until stage 1 is fully complete. Within a single stage, all assigned recipients are notified and act in parallel.

**Recipient** — a person assigned to a stage (can also be an automatic stage without any interaction needed) . They receive an invitation (by email, SMS, or WhatsApp), open the document, and perform whatever action their stage requires.

**File and Field Tasks** — documents attached to the envelope with interactive fields (signatures, checkboxes, text inputs) positioned on specific pages. Each field is linked to a specific recipient, so each person only sees and interacts with the fields assigned to them.

## Documents

An envelope can contain one or more documents. Each document is uploaded as a separate PDF file to the envelope via a multipart/form-data request.

### Uploading Files

Uploading a file does not yet make it interactive — it simply attaches it to the envelope and returns a `fileId`. The interactive elements are added separately through field tasks.

In a multi-document workflow, recipients may have fields on some documents but not others, and the same document can have fields assigned to different recipients.

## Stages in Depth

Stages are the primary mechanism for controlling the flow and order of a signing process.

### Sequential Execution

Stages are numbered and execute in the order they were created. The second stage is not triggered until every required action in the first stage is complete. This makes it straightforward to model approval chains, countersignatures, and other multi-step processes.

### Stage Types

Each stage has a type that defines what the recipients in that stage are expected to do:

| Type | What recipients do |
|  --- | --- |
| `Signer` | Sign or interact with signature fields in the document |
| `Approver` | Approve or reject the envelope before it moves to the next stage |
| `CarbonCopy` | Receive a copy of the envelope for awareness — no action required |
| `Viewer` | View the document — no action required |
| `Automatic` | System-driven step with no human recipient |


An envelope typically starts with one or more `Signer` stages, but you can place any combination in any order. A common pattern is an `Approver` stage before a `Signer` stage, so someone internal reviews the document before it goes to the external signer.

### Controlling How Many Recipients Must Complete a Stage

By default, all recipients in a stage must complete their action before the stage advances. You can change this with `requiredRecipientCompletions`.

This field accepts an integer — the minimum number of recipients who must complete the stage for it to be considered done. If you have three recipients in a stage but set `requiredRecipientCompletions` to 1, the stage completes as soon as any one of them signs. This is useful for scenarios like:

- **Committee signing**: send to five board members, require two to sign.
- **Authorized signatory pools**: send to three authorized signers, any one of whom may sign on behalf of the group.
If `requiredRecipientCompletions` is not set, it defaults to the total number of recipients in the stage (all must complete).


## Recipient Configuration

Each recipient is configured at the stage level and can be configured before any documents or fields are set up. The recipient record controls identity, communication, access security, and — where required — the pre-configuration data needed for certificate-based signatures.

### Identity and Contact Details

A recipient is identified by their given name, surname, email address, and optionally a phone number. The phone number is required when SMS-based authentication or OTP signing is used.

### Notification Channels

You control how the recipient receives their invitation and any reminders via `notificationChannels`. The available options are `Email`, `Sms`, and `WhatsApp`.

### Language

The `languageCode` field sets the language used for all emails, SMS messages, and UI elements shown to this recipient. Useful when your workflow involves recipients in different countries.

### Authentication

Authentication adds an identity check that the recipient must pass before they can access the document. Three mechanisms are available and can be combined:

- **Access code** — a static secret you define. The recipient must enter the correct code to open the envelope. You share the code with them through your own channel.
- **OTP via SMS** — a one-time password sent to a phone number at the moment the recipient tries to open the document. You specify the phone number when setting up the recipient.
- **OAuth** — the recipient authenticates through an external identity provider. You supply the provider name and the recipient's external identifier to link the accounts.


### Signature Configuration

The signature configuration on the recipient is only needed for signing methods that require pre-provisioned data — specifically:

- **Disposable certificate** — a single-use qualified certificate issued at signing time. You provide the recipient's identification document details (type, number, issuing country, expiry, and so on) and a verification phone number. The platform uses this to issue the certificate during the signing session.
- **Remote certificate** — the recipient signs using a certificate stored in a remote signing service. You provide the user ID and device ID that identify their certificate in that service.
- **OTP signature** — an SMS one-time password that acts as the signature itself (not to be confused with OTP as an access authentication method). You provide the phone number to which the OTP is sent at the moment of signing.
- **Signing plugins** — third-party signing integrations. You specify the plugin ID and any key/value settings the plugin requires.
For all other signing methods — click-to-sign, draw-to-sign, type-to-sign, biometric, local certificate — no pre-configuration is needed on the recipient. The allowed methods are instead controlled by `allowedSignatureTypes` on the signature field itself, which is set when placing the field on the document.


### Personal Message

A free-text message shown to the recipient alongside the standard invitation. Use it to provide context — for example, explaining which document they are signing or any instructions specific to this envelope.

## Workflow Scenarios

The following scenarios illustrate how stages and recipients combine to handle common real-world cases.

### Scenario 1 — Single Signer

The simplest workflow: one document, one person to sign.

```
Stage 1 (Signer)
  └── Alice
```

Alice receives an invitation, opens the document, places her signature, and the envelope completes.

### Scenario 2 — Two Signers in Sequence

Both parties must sign, and the order matters. The contract goes to the first party first; only after they sign does the second party receive their invitation.

```
Stage 1 (Signer)   →   Stage 2 (Signer)
  └── Alice                └── Bob
```

This is common for bilateral contracts where one side initiates and the other countersigns.

### Scenario 3 — Multiple Signers in Parallel

Two or more people must sign, but the order does not matter. They all receive their invitations at the same time and can sign independently.

```
Stage 1 (Signer)
  ├── Alice
  └── Bob
```

Both Alice and Bob receive their invitation simultaneously. The envelope does not complete until both have signed (`requiredRecipientCompletions` = 2, which is also the default when two recipients are present).

### Scenario 4 — Group Signing (N of M)

Three authorized signers are on the list, but any one of them is sufficient to execute the agreement.

```
Stage 1 (Signer) — requiredRecipientCompletions: 1
  ├── Alice
  ├── Bob
  └── Carol
```

All three receive the invitation at the same time. The envelope advances as soon as one of them signs. The other two are no longer required to act.

This pattern is also used for majority-vote scenarios — for example, requiring 3 out of 5 board members to sign.

### Scenario 5 — Internal Approval Before External Signing

A document must be approved by an internal reviewer before it is sent to the customer for signature.

```
Stage 1 (Approver)   →   Stage 2 (Signer)
  └── Internal Manager       └── Customer
```

The manager receives the document first and either approves or rejects it. If approved, stage 2 is triggered and the customer receives their signing invitation. If rejected, the envelope stops and the sender is notified.

### Scenario 6 — Signing Followed by Carbon Copy Notification

After all parties have signed, a third party (such as a legal department or archive system) should receive a copy of the completed document automatically.

```
Stage 1 (Signer)   →   Stage 2 (CarbonCopy)
  ├── Alice                └── Legal Team
  └── Bob
```

The CarbonCopy stage recipient does not take any action — they simply receive the envelope as a notification once the previous stages complete. This is a clean way to ensure the right people are informed without requiring them to log in or interact with the document.

### Scenario 7 — Multi-Stage with Mixed Types

A complex workflow combining approval, parallel signing, and notification:

```
Stage 1 (Approver)   →   Stage 2 (Signer)        →   Stage 3 (CarbonCopy)
  └── Legal Reviewer       ├── Party A                  └── Archive System
                           └── Party B
```

The legal reviewer approves the document first. Both parties then receive their invitations simultaneously and must both sign. After that, the archive system gets the completed document automatically.

## Field Tasks

Field tasks are the connection between a position on a document and a recipient. A task defines:

- **What type of interaction** is expected (a signature, a checkbox, a text input, and so on)
- **Where on the document** the field appears (which page, and the x/y coordinates of the field's top-left corner, expressed in PDF page units)
- **How large the field is** (width and height)
- **Who is responsible** for completing it (the `recipientId`)
- **In what order** the fields are presented to the signer (`sortOrder`)
Field tasks are set per file using a PUT request. This call is a full replacement — it sets the complete list of tasks for that document. If you call it a second time with a modified list, the previous tasks are discarded entirely and the new list takes effect.


### Field Types

The `fieldType` property on a field task determines what the recipient sees and what they are expected to do:

| Field type | What it does |
|  --- | --- |
| `Signature` | The recipient places a signature. The allowed signing methods are controlled by `allowedSignatureTypes` on the field itself. |
| `TextInput` | The recipient enters text (specific formats e.g. date, number can be set as sender). |
| `Checkbox` | The recipient checks or unchecks a box. |
| `Radiobutton` | The recipient selects one of the provided radio button. |
| `DropDown` | The recipient selects a value from a predefined dropdown list. |
| `ListBox` | The recipient selects one or more values from a visible list. |
| `Attachment` | The recipient uploads a file as part of their response. |
| `AreaReadConfirmation` | The recipient must explicitly confirm they have read a specific area within a page. |
| `PageReadConfirmation` | The recipient must confirm they have read an entire page before proceeding. |
| `FileReadConfirmation` | The recipient must confirm they have read the entire document. |
| `Link` | Displays a clickable link within the document, typically pointing to an external resource the recipient should review. |
| `Approval` | The recipient approves by clicking on the field (similar mechanism as the ClickToSign Signature) |


### Signature Field and Allowed Signing Methods

For `Signature` fields specifically, you can restrict which signing methods the recipient may choose from by setting `allowedSignatureTypes` on the field. If you leave this empty or null, the organization's default configuration applies.

The confirmed signature types are:

| Signature type | Description |
|  --- | --- |
| `ClickToSignSignature` | The recipient clicks a button to confirm their signature — no drawing or certificate required. |
| `DrawToSignSignature` | The recipient draws their signature using a mouse or touchscreen. |
| `TypeToSignSignature` | The recipient types their name and it is rendered as a signature. |
| `BiometricSignature` | Captures biometric data (pressure, speed, rhythm) during the signing gesture. |
| `LocalCertificateSignature` | The recipient signs using a certificate stored on their local device (e.g. a smart card or USB token). |
| `DisposableCertificateSignature` | A single-use qualified certificate is issued at the moment of signing. Requires pre-configuration on the recipient. |
| `RemoteCertificateSignature` | The recipient signs using a certificate stored in a remote signing service. Requires pre-configuration on the recipient. |
| `OneTimePasswordSignature` | An OTP sent via SMS acts as the signature. Requires pre-configuration on the recipient. |
| `AutomaticSignature` | Signing is done without any human interaction. |
| `PluginSignature` | Signing is handled by a third-party plugin integration. Requires plugin configuration on the recipient. |


This is distinct from the `signatureConfiguration` on the recipient. The field's `allowedSignatureTypes` controls what methods are offered in the UI. The recipient's `signatureConfiguration` provides the pre-provisioned data required by methods that need it (disposable certificate, remote certificate, OTP signature, signing plugins). For all other methods the field configuration alone is sufficient — no additional data needs to be set on the recipient.

### Annotations

Following annotations can be added:

- Text
  - Define a text visible to the recipient on the document
- Date
  - Adds the date to the document
- FullName
  - Adds the full name of the recipient to the document
- FirstName
  - Adds the first name of the recipient to the document
- LastName
  - Adds the last name of the recipient to the document
- Initials
  - Adds the initials of the recipient to the document
- Email
  - Adds the email address of the recipient to the document


### Positioning Fields

Field position and size are defined in PDF page coordinate units:

- `positionX` and `positionY` are the coordinates of the field's top-left corner on the page
- `width` and `height` define the size of the field
- `page` specifies which page of the document the field appears on (1-indexed)


### Assigning Multiple Fields to the Same Recipient

A single recipient can have multiple field tasks across one or more documents. The `sortOrder` property controls the sequence in which the fields are presented to them during their signing session. Fields with a lower sort order are shown first. This allows you to guide the signer through a document in a logical order regardless of where the fields are physically positioned on the page.

## The Envelope Lifecycle

Once an envelope is sent it moves through a defined set of states:

```
draft → sent → completed
                ↘ rejected
                ↘ expired
                ↘ cancelled
```

| Status | What it means |
|  --- | --- |
| `draft` | The envelope has been created but not yet sent. It can still be edited. |
| `sent` | Recipients have been notified and the workflow is active. |
| `completed` | All required stages have been completed successfully. |
| `rejected` | A recipient rejected the document. |
| `expired` | The deadline passed before the workflow completed. |
| `cancelled` | The sender manually stopped the process. |


Once an envelope reaches a terminal state (`completed`, `rejected`, `expired`, `cancelled`) it can no longer be modified or advanced. The signed documents and audit trail become available for download from the artifacts endpoint.

## Using Templates for Repeating Workflows

If you send the same document structure repeatedly — the same stages, the same field layout, the same signing order — you can define all of this once as a template. When a new envelope is needed, you create it from the template with a single API call. The resulting envelope is an independent copy and can be edited before sending if needed.

Templates are particularly useful when:

- The document changes each time but the workflow structure is always the same.
- Many envelopes need to be created programmatically in bulk.
- You want to enforce a standard signing process across your organization.


## Key Design Principles

A few things to keep in mind when designing your integration:

**Everything is scoped to the organization.** All API calls include the `organizationId` in the path. This is your tenant identifier and determines which configuration, templates, and completed envelopes are accessible.

**Fields are assigned to recipients, not to stages.** Placing a signature field requires the specific `recipientId`. This means you must add stages and recipients first, then place the field tasks.

**The send call is the point of no return.** Until you call the send endpoint, the envelope stays in `draft` and can be freely modified. Once sent, the workflow is live and recipients are notified.

**Stage completion triggers the next stage automatically.** You do not need to poll and manually advance the workflow. Once a stage reaches its required number of completions, the API triggers the next stage and sends invitations to the next set of recipients.

For a complete envelope workflow please see the following guide: [Envelope-Workflow](/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/03-developer-documentation/01-api-reference/basic-envelope-workflow)

For a complete template worklow please see the following guide:
[Template-Workflow](/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/03-developer-documentation/01-api-reference/basic-template-workflow)