--- title: "Specify Recipients" slug: "specify-recipients-restapi" updated: 2026-07-03T19:23:14Z published: 2026-07-03T19:23:14Z canonical: "docs.onespan.com/specify-recipients-restapi" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.onespan.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/v1/docs/downloading-sdks). This feature must also be enabled for your account. To do this, contact our [Support Team](https://www.onespan.com/support). 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 ```http POST /api/packages ``` ### HTTP Headers ```http Accept: application/json Content-Type: application/json Authorization: Basic api_key ``` ### Request Payload ```json {  "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 ```json {  "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 | Property | Type | Editable | Required | Default | Sample Values | | --- | --- | --- | --- | --- | --- | | name | string | Yes | Yes | n/a | Contract Review | | roles | array | Yes | Yes | n/a | | | name | string | Yes | No | n/a | UnknownSigner | | type | string | Yes | Yes | SIGNER | PLACEHOLDER | | signers | array | Yes | Yes | n/a | [{}] | | documents | array | Yes | Yes | n/a | | ## 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 ```http POST /api/packages/{packageId}/roles ``` ### HTTP Headers ```http Accept: application/json Content-Type: application/json Authorization: Basic api_key ``` ### Request Payload ```json {  "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 ```json {  "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 | Property | Type | Editable | Required | Default | Sample Values | | --- | --- | --- | --- | --- | --- | | name | string | Yes | No | n/a | RecipientSpecifier | | specifier | boolean | Yes | No | false | true | | signers | array | Yes | Yes | n/a | | | email | string | Yes | Yes | n/a | jane.doe@example.com | | firstName | string | Yes | Yes | n/a | Jane | | lastName | string | Yes | Yes | n/a | Doe | ## 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 ```http POST /api/packages/{packageId}/status ``` ### HTTP Headers ```http Accept: application/json Content-Type: application/json Authorization: Basic api_key ``` Request Payload ```json {  "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. The warning about sending a transaction with a specifier but no placeholders (displayed in the Sender UI) is not enforced by the API. The transaction is sent directly. ### Request Payload Table | Property | Type | Editable | Required | Default | Sample Values | | --- | --- | --- | --- | --- | --- | | status | string | Yes | Yes | n/a | SENT | ## 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 ```http POST /api/packages/{packageId}/roles/{roleId}/signingUrl ``` ### HTTP Headers ```http Accept: application/json Content-Type: application/json Authorization: Basic api_key ``` ### Response Payload ```json {  "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 | Property | Type | Description | | --- | --- | --- | | url | string | A secure, tokenized URL that directs the specifier to the appropriate page based on the transaction state. | ## Retrieving the Audit Trail All actions taken by the **Recipient Specifier** are recorded in the transaction's [Evidence Summary](/v1/docs/downloading-signed-documents-and-evidence-summaries). You can retrieve the audit trail using the standard audit endpoint and filter for Specify Recipient events. ### HTTP Request ```http GET /api/packages/{packageId}/audit ``` ### HTTP Headers ```http 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.