Specify Recipients

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:

1. Sender creates a transaction.

2. Sender adds placeholder roles instead of selecting named recipients.

3. Sender designates a "Recipient Specifier". This is the person who will later identify the real signers.

4. The transaction is sent and the system moves into a SENT state.

5. A notification is sent to the Recipient Specifier.

6. The Recipient Specifier enters the actual recipient name/email for one, some, or all placeholder roles.

7. The workflow resumes and the newly designated signers are notified to complete signing.

Creating a Transaction with a Placeholder Recipient

A new role type called PLACEHOLDER has been created to officially denote unidentified recipients. This replaces the previous method of generating a signer object with blank name/email fields. The PLACEHOLDER role type is applicable in transactions only when the Specify Recipient account feature is activated.

HTTP Request

POST /api/packages

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
  "name": "Contract Review",
  "roles": [
      {
      "name": "UnknownSigner",
      "type": "PLACEHOLDER",
      "signers": [{}]
    }
  ],
  "documents": [...]
}

For a complete description of each field, see the Request Payload table below.

Response Payload

{
  "id": "abc123packageId",
}

Results

After you run your code, a transaction is created with a placeholder for the recipient. This placeholder doesn't have a name or email yet — those details will be filled in by the Recipient Specifier before the signing ceremony starts.

Request Payload Table

Setting a Recipient Specifier

The specifier is defined by setting the specifier property of the role object to true on a role's signer object. Note that only one specifier is permitted for each transaction.

HTTP Request

POST /api/packages/{packageId}/roles

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
  "name": "RecipientSpecifier",
  "specifier": true,
  "signers": [
   {
     "email": "jane.doe@example.com",
     "firstName": "Jane",
     "lastName": "Doe"
   }
  ]
}

For a complete description of each field, see the Request Payload table below.

Response Payload

{
  "id": "RecipientSpecifier",
  "name": "RecipientSpecifier",
  "type": "SIGNER",
  "reassign": false,
  "index": 0,
  "signers": [
    {
      "email": "jane.doe@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "id": "RecipientSpecifier",
      "delivery": {
        "provider": false,
        "email": true,
        "download": false
      },
      "auth": {
        "scheme": "NONE",
        "challenges": []
      },
      "title": "",
      "company": "",
      "specifier": true,
      "created": "2026-06-29T12:00:00Z",
      "updated": "2026-06-29T12:00:00Z"
    }
  ]
}

Results

After running your code, the designated recipient is marked as the Recipient Specifier for the transaction. When the transaction is sent, only this recipient will be notified first, and they will be directed to the Specify Recipients page to fill in the details of any placeholder recipients.

Request Payload Table

Sending a Transaction

Sending a transaction using APIs follows the standard status-change endpoint. The Specify Recipient validations are applied automatically. No UI confirmation prompts are shown when sending via API — the transaction is sent directly if validations pass.

HTTP Request

POST /api/packages/{packageId}/status

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
  "status": "SENT"
}

For a complete description of each field, see the Request Payload table below.

Results

After executing your code, the status of the transaction updates to SENT. If the transaction features a Recipient Specifier along with placeholder recipients, the system proceeds to the specifier step: only the Recipient Specifier receives a notification, and signing invitations are delayed until the specifier finalizes their action.

Request Payload Table

Generating the Specifier Signing URL

The specifier's signing URL is generated using the standard signing URL endpoint. When the transaction is in the specifier step, the URL automatically routes to the Specify Recipients page instead of the signing ceremony.

HTTP Request

POST /api/packages/{packageId}/roles/{roleId}/signingUrl

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Response Payload

{
  "url": "https://sandbox.esignlive.com/auth?sessionToken=abc123"
}

Results

After executing your code, a secure link is generated that leads the Recipient Specifier to the Specify Recipients page. The following actions are determined by the state of the transaction:

• During the specifier step: The URL takes the specifier to the Specify Recipients page.

• After specification is complete: The URL points to the signing ceremony.

• For a non-specifier signer during the specifier step: A 400 error is returned.

Response Payload Table

Retrieving the Audit Trail

All actions taken by the Recipient Specifier are recorded in the transaction's Evidence Summary. You can retrieve the audit trail using the standard audit endpoint and filter for Specify Recipient events.

HTTP Request

GET /api/packages/{packageId}/audit

HTTP Headers

Accept: application/json
Authorization: Basic api_key

Results

After running your code, the Evidence Summary is returned. Filter the response by the name field for Specify Recipient events:

• Recipient Specifier Session for Recipient — Recorded each time the specifier opens or re-opens a session on the Specify Recipients page.

• Recipient removed — Recorded when the specifier deletes a placeholder from the Specify Recipients page.

• Recipient specification complete — Recorded when the specifier submits the form, capturing which placeholders were replaced and which were removed.