The Specify Recipient feature lets you send a transaction even when you don't yet know who the final signers will be. Instead of entering specific people up front, the sender adds placeholder roles and assigns one person as the Recipient Specifier. After the transaction is sent, the Recipient Specifier identifies the real signers, and the signing workflow continues.
If you intend to use one of OneSpan's SDKs to use this feature, you must install the latest version of SDKs. To install the latest SDKS see Downloading SDKS. This feature must also be enabled for your account. To do this, contact our Support Team.
For example:
The sender knows which roles must sign, but not the specific individuals.
A coordinator or manager needs to fill in signer details after the transaction is created.
The general workflow is as follows:
Sender creates a transaction.
Sender adds placeholder roles instead of selecting named recipients.
Sender designates a "Recipient Specifier". This is the person who will later identify the real signers.
The transaction is sent and the system moves into a SENT state.
A notification is sent to the Recipient Specifier.
The Recipient Specifier enters the actual recipient name/email for one, some, or all placeholder roles.
The workflow resumes and the newly designated signers are notified to complete signing.
Key Concepts
Concept | Description |
|---|---|
Placeholder Recipient | A required signer role that does not yet have a real person assigned (e.g., "Borrower", "Approver", "Witness"). Uses the PLACEHOLDER signer type. |
Recipient Specifier | The single person responsible for identifying the real recipients for the placeholder roles after the transaction is sent. |
Specifier Step | The phase of a transaction lifecycle where the workflow is paused, so that the Recipient Specifier can complete their task. |
SENT State | The OneSpan Sign transaction status used during the Specifier step. The transaction is marked as SENT, but the signing invites are held back until everything is specified. |
Specify Recipients Page | A specific page in the Signer UI that the Recipient Specifier uses to fill in the placeholder details and to send the form. |
Only one Recipient Specifier (managing signer) is allowed per transaction.
Duplicate Signers
Specify Recipient supports duplicate signers. If the Recipient Specifier replaces a placeholder role with themselves, and they are already a signer elsewhere in the transaction, the two entries are merged where possible.
Specifying Recipients from the Sender Interface
Recipient specification can now be performed directly from within the sender interface, in addition to the notification-based workflow described above.
If the Recipient Specifier has actions to perform on the transaction's documents and it is their turn to sign, they are taken directly to the signing ceremony after specifying recipients.
Sending a Specify Recipient Transaction
To send a Specify Recipient transaction:
When Adding Recipients to a transaction select the recipient who will be the Recipient Specifier. This is the person will identify the actual signers for the transaction. Add them to the transaction as you would a regular signer.
Click the ellipsis beside this recipient (...) and then click Advanced Settings.
Toggle the Specify placeholder recipients option and click Save.
Add as many Placeholder recipients as you need. To do this, add a recipient, enter a Placeholder Name, and then click the recipient icon
to the left of their name. From there, select Placeholder as the recipient type.
Continue editing your transaction as per usual (documents, signature fields, etc.) and then send the transaction for signing.
Once the designated Recipient Specifier receives the transaction, they will then be responsible for providing the actual recipient's information for each Placeholder. These signers will then be directed to the signing ceremony.
Previewing Documents Before Specification
Before completing specification, the Recipient Specifier can preview the transaction's documents to confirm exactly which signatures and fields belong to each placeholder, rather than assigning recipients based on role name alone. Only placeholder fields are shown — fields belonging to named recipients (senders, regular signers) do not appear in any preview mode.
Mode | Description |
|---|---|
All placeholders | Displays every transaction document with the signatures and fields of all placeholders needing specification. Fields are color-coded using the same placeholder color scheme described under Placeholder List Display. |
Single placeholder | A "Preview as recipient" option next to each placeholder opens a modal scoped to only the documents on which that placeholder has signatures or fields. |
Thumbnail | Clicking a document thumbnail opens a full-page preview, auto-scrolled to the relevant page, with the ability to scroll up or down through the remaining documents from within the same view. |
Previewing a Single Placeholder
To preview the documents for a single placeholder:
From the Specify Recipients page, locate the placeholder in the list.
Select Preview as recipient.
The preview modal opens, scoped to the documents containing that placeholder's fields.
Close the modal to return to the Specify Recipients page.
The document preview displays the placeholder's status and required action directly above its document, so the specifier does not mistake the absence of visible fields for the absence of any required action. This applies whether the placeholder is a reviewer, a signer, or an accept-only recipient.
The documents within the preview are based on the specifier's document visibility.
Available Actions
The Recipient Specifier has access to the following actions while specifying recipients:
Action | Behavior |
|---|---|
Save on blur | Saves current entries without submitting. The specifier can close and return later. |
Remove Placeholder | Deletes a placeholder from the transaction. Displays the confirmation message: "This action will permanently remove the recipient from the transaction. Do you want to continue?" |
Add Personal Message | Appears if no personal message was set by the sender. Allows the specifier to add one. |
Submit | Triggers a confirmation dialog before finalizing. |
Submitting the Form
Clicking Submit displays the following confirmation dialog:
"Submitting the form will perform all replacements, remove any unidentified recipients, and initiate the transaction signing. Once submitted, you will no longer be able to make any changes to the recipients. Do you want to continue?"
Confirm: Performs the placeholder replacements, removes any remaining unspecified placeholders, and sends the transaction for signing.
Cancel: Returns to the Specify Recipients page without changes.
Auto-Submit on Last Placeholder Deletion
If the specifier deletes the last remaining placeholder and no other recipients require specification, the form is auto-submitted. The confirmation message reads:
"This action will permanently remove the recipient from the transaction and auto-submit the form. Do you want to continue?"
Disputing a Recipient Specification
In addition to completing specification, the Recipient Specifier can dispute (decline) the request instead — returning the transaction to the sender with a reason, rather than leaving it stalled or attempting to specify recipients incorrectly.
Disputing a Specification
To dispute a recipient specification request:
From the Specify Recipients page, open More Actions.
Select Dispute.
In the "Dispute Recipient Specification" panel, enter a reason in the required Enter a reason field. The Dispute button is disabled until a reason is entered.
Select Dispute to submit, or Cancel to return to the Specify Recipients page without disputing.
Outcome
Disputing a recipient specification has the following effects:
Element | Value |
|---|---|
Transaction status | Set to Draft (Declined). |
Specifier confirmation page | Title: "Recipient Specification Disputed." Body: "You have disputed the recipient specification for this transaction. An email notification has been sent to the transaction sender." |
Handover URL | Not followed on dispute, even if one is configured. |
Dashboard indicator | An "i" icon appears next to the transaction name in the Drafts folder. Tooltip: "This transaction has been disputed." |
Transaction Edit page | Displays "Please review the details of '{transaction name}' cancellation," with the dispute reason included in the "Cancellation Details for {transaction name}" modal. |
Re-accessing the specifier/signing link | Displays an error page. Title: "Transaction Disputed." Body: "This transaction is no longer available as it has been disputed. Please contact the transaction sender for further information." |