--- title: "Creating Transactions Programmatically" slug: "creating-transactions-programmatically" updated: 2026-01-15T18:21:54Z published: 2026-01-15T20:28:26Z canonical: "docs.onespan.com/creating-transactions-programmatically" --- > ## 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. # Creating Transactions Programmatically OneSpan Sign for Salesforce enables you to create OneSpan Sign transactions programmatically. There are two main ways of doing so: - [Creating a Transaction from a Custom Button](/v1/docs/creating-transactions-programmatically#creating-a-transaction-from-a-custom-button) - [Creating a Transaction from a Custom Action](/v1/docs/creating-transactions-programmatically#creating-a-transaction-from-a-custom-action) The following section provides information relevant to both of the above procedures: - [Parameters for URL Code Snippets](/v1/docs/creating-transactions-programmatically#parameters-for-url-code-snippets) The URL that appears in the code examples below must start with the character string `/apex/esl__package?`. This is the URL required to access a OneSpan Sign transaction's *Visualforce* page. ## Creating a Transaction from a Custom Button If you create a Custom Button, and add it to a Salesforce object, the added button enables Salesforce users to send documents to be signed from that object’s records. You can create a transaction from a Custom Button in the following ways: - [Creating a Transaction from a Template](/v1/docs/creating-transactions-programmatically#creating-a-transaction-from-a-template) - [Creating a Transaction from a Salesforce ID or an Email Address](/v1/docs/creating-transactions-programmatically#creating-a-transaction-from-a-salesforce-id-or-an-email-address) - [Creating a Transaction from a Convention](/v1/docs/creating-transactions-programmatically#creating-a-transaction-from-a-convention) ### Creating a Transaction from a Template To create a package programmatically from a template: - Write and then run code that will create a package from a template. You must specify the following *template* parameters: - `ParentId` - `Name` - `TemplateId` At the end of this procedure, you should see all the template's information reflected in the created package. #### Example When the following code snippet is run, it creates a OneSpan Sign package from a template for a particular account: ```plaintext /apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&TemplateID=a0G360000018BdREAU ``` ### Creating a Transaction from a Salesforce ID or an Email Address When creating a transaction from a Salesforce ID you must specify the following parameters: - `Name` - `SignerN` — This can be either a Salesforce ID (see [Example 1](/v1/docs/creating-transactions-programmatically#example-1)) or an email address for the Nth recipient (see [Example 2](/v1/docs/creating-transactions-programmatically#example-2)). If `SignerN` is an email address, the following parameters are also required: - `SignerNFirstName` - `SignerNLastName` - `Documents` > OneSpan Sign supports the following document types: > > - Adobe's *Portable Document Format* (*.*pdf*) — PDFs on which OneSpan Sign can act generally have at least these permissions enabled: (1) Changing the Document; (2) Signing; (3) Filling of form fields. > - Microsoft Word (*.*doc* or *.*docx*) > - Open Office (*.*odt*) > - Text (*.txt) > - Rich Text Format (*.rtf) > > In addition, the OneSpan Sign Print Driver supports any document that can be printed from a Windows-based application (e.g., Microsoft Word, Microsoft Excel, Microsoft PowerPoint). > File Size Constraints > > - The maximum size of a single document is 16 MB. Smaller documents yield better performance — we recommend under 5 MB per document. > - The maximum total size of all documents in a transaction is 39MB. > - If your organization uses Salesforce or Microsoft SharePoint connectors, the file size maximum is 5 MB per document. > - If your organization uses Salesforce connectors, the maximum number of documents that can be added to a transaction is ten (10). > - If you enable email delivery while configuring a recipient, attachments larger than 5 MB are not supported. > > File Name Constraints > > - Document file names should not contain any of the following comma-separated characters: *, /, \, :, <, >, |, ?, ". > - A document's name cannot contain the string esigned. > > General File Constraints > > - We recommend that you do not use PDF documents that make use of XML Forms Architecture. For more information, see XFA Support. > - Do not upload password-protected or corrupted documents. These will generate an error. > - OneSpan strongly recommends that you scan a PDF for syntax errors (e.g., by using Adobe's Preflight tool), and resolve any errors before you add the document to a transaction. > - PDFs with the NeedAppearances flag set to true are not currently supported. At the end of this procedure, you should see the provided information reflected in the created package. #### Example 1 When the following code snippet is run, it creates a OneSpan Sign package from the ID of a contact: /apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Signer1=00336000003gBYX&Documents=00P36000000wwrd #### Example 2 When the following code snippet is run, it creates a OneSpan Sign package from an email address. In particular, this snippet creates a recipient of type `External Email` with the email address `john.doe@test.com`. /apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Signer1=john.doe@test.com&Signer1FirstName=john&Signer1LastName=doe&Documents=00P36000000wwrd ### Creating a Transaction from a Convention To create a transaction from a Convention with the help of customized code: 1. Create a suitable Convention. For more information, see [Automation via OneSpan Sign Conventions](/v1/docs/salesforce-integrators-introducing-onespan-sign-conventions). 2. Create a Custom button that will run the necessary code when the button is clicked (see the example below). 3. Click the Custom button. Doing so should create a transaction with the information specified in the Convention. When the following code snippet is run, it creates a OneSpan Sign transaction from a Convention, where: - The `ConventionId` is the ID of the Convention to be used. - `Signer1Label` is the ID of the Recipient Label to be applied to Signer1 /apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Documents=00P36000000wwrd&ConventionId=a0836000000nfRo&Signer1=00336000003gBYX&Signer1Label=a0K36000001j8VW ## Creating a Transaction from a Custom Action If you create a Custom Action, and add it to a Salesforce object, the added action enables *Lightning Experience* users to easily send documents to be signed via OneSpan Sign. The URL used in the procedure for a Custom Action is the same as that for a Custom Button, except that the URL for a Custom Action must be stored in a custom field created on the object. To create a transaction via a Custom Action, perform the steps below: - [Step 1: Create a field that will store the automation URL.](/v1/docs/creating-transactions-programmatically#step1) - [Step 2: Create a Visualforce page to trigger the automation.](/v1/docs/creating-transactions-programmatically#step2) - [Step 3: Create the action in the component, and associate the Visualforce page with it.](/v1/docs/creating-transactions-programmatically#step3) - [Step 4: Add the action to the Page Layout.](/v1/docs/creating-transactions-programmatically#step4)

Step 1: Create a field that will store the automation URL.

 In this step, you must create a field in the object (Account, Contact, Opportunity, etc) that will store the Automation URL. That URL follows the same rules as for the Custom Button, and it receives the same parameters. We recommend using formula fields, so you can use "merge fields".

Step 2: Create a Visualforce page to trigger the automation.

 In the Visualforce page, the Admin user must use a component supplied by the connector to: (1) read the Automation URL stored in the field created above; (2) trigger the automation. To create the Visualforce page: 1. Click Setup. 2. In the left pane, click Develop > Visualforce pages. A list of Visualforce pages appears. 3. Click New. 4. Type a suitable Label, Name, and Description for the new page. 5. Select the Available for Salesforce mobile apps and Lighting Pages check box. 6. On the Visualforce Markup tab, type the following code: ![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/vf_page.png) After the Admin user has created the Visualforce page, they must specify: (1) the name of the object that will use that page (e.g., Account, Contact, Opportunity, a custom object, etc.); (2) the name of the field where the URL is stored.

Step 3: Create the action in the component, and associate the Visualforce page with it.

 1. Click Setup. 2. If you want to use a standard object, in the left pane click Customize, and select the object. 3. If you want to use a custom object: 1. In the left pane, click Create > Objects. A new page displays a list of custom objects. 2. Find the relevant custom object, and click its name. 4. In the Buttons, Links, and Actions section, click New Action. A New Action page opens. 5. Under Action Type, select Custom Visualforce. 6. Under Visualforce Page, select the Visualforce page you created earlier. 7. Type a suitable Label and Name for the new Custom Action. 8. Click Save.

Step 4: Add the action to the Page Layout.

 Once the action has been created, the Admin user must add it to the Page Layout to make it accessible to other users. It must also be added to the *Salesforce1* actions to make it available on mobile devices. To add the new Custom Action to the Page Layout for your custom object: 1. Click Setup. 2. In the left pane, click Create > Objects. A new page displays a list of custom objects. 3. Find your custom object, and click its name. 4. On the Page Layouts section, click Edit. The Page Layout page appears. 5. Click the Mobile and Lightning option in the top left pane. 6. If you don't see any actions in the Mobile and Lightning Experience Actions section, click the wrench icon that appears when you move your mouse over that section. 7. Drag the new Custom Action into the Mobile and Lightning Experience Actions section. 8. Click Save. At the end of this procedure, you should see all input information reflected in the created transaction. ## Parameters for URL Code Snippets The following table describes parameters that can be used in URL code snippets for all of the above procedures. A *static sample* has a fixed value. The value of a *dynamic sample* is specified by a merged field. | Parameter Name | Description | Static Sample | Dynamic Sample | | --- | --- | --- | --- | | TemplateId | The transaction's template ID. If it's not provided, create it *ad hoc*. Any field specified in the URL will override the value of the template. The template must be active. | `TemplateId=a0Ag0000007r4nS` | `TemplateId={!Account.Transaction_Template__c}` | | Name | The transaction's name, URL-encoded. | `Name=My %20Transaction` | `Name={!Contact.Name} %20Transaction` | | Description | The transaction's description, URL-encoded. | `Description=The %20Transaction %20Description` | `Description={!Contact.FirstName} %20{!Contact.LastName}-The %20Transaction %20Description` | | ExpiryDate | The transaction's expiration date (YYYYMMDD) | `ExpiryDate=20151230` | `ExpiryDate={!Contact.ExpiryDate__c}` | | EmailMessage | The values enter into EmailMessage will be passed to the “$PACKAGE_MESSAGE;” placeholder existing default templates, such as the “email.activate” template and the “email.notify” template. For more information see [OneSpan Sign Developers: Email Templates](https://www.onespan.com/blog/onespan-sign-developers-email-templates-part-1). | `EmailMessage=Content %20of %20the %20email %20to %20send` | `EmailMessage={!Account.CustomEmail__c}` | | Language | The language of the transaction package. The options available are based on the language selections made on the [Customization page](/v1/docs/customizing-onespan-sign-embedded-integration-for-salesforce#selecting-display-languages). | `Language=en` | `Language={!Contant.CommunicationLanguage__c}` | | InPersonSigning | Flag that specifies if in-person signing is *true* or *false* | `InPersonSigning=true` | `InPersonSigning={!Contact.InPersonSigning__c}` | | Documents | List of comma-separated IDs. Those IDs can be for Salesforce attachments, Salesforce documents, or Salesforce files. Create a transaction attachment, document, or file with its binary, and with a related name that corresponds to the item's order in the list. Note: Salesforce files became supported only in OneSpan Sign Embedded Integration for Salesforce 4.10. The system supports a maximum of 5 MB per document (smaller documents yield better performance — we recommend under 5 MB per document). The system supports a maximum of 10 documents per transaction or transaction template. However, there is no limit to the total collective size of documents in a transaction. | `Documents=015g0000000Cm1f, 00Pg0000001eg9H` | `Documents={!Account.DocumentId__c}` | | Send | Flag that indicates if the transaction must be sent after being created. Requires a default Convention or the *conventionID* parameter, and a Recipient Label for at least one of the recipients. | `Send=1` or `Send=true` | `Send={!Account.AutomaticallySend__c}` | | ConventionId | The Convention ID that will be used to prepare and send the transaction. *ConventionId* is mandatory if no default Convention has been set in the Custom Settings. | `ConventionId=a0Rg00000033spu` | `ConventionId={!Account.Convention__c}` | | retUrl | The URL to which users will be directed once the transaction has been sent. It must have *Send=1* or *Send=true*, and it must be URL-encoded. | `retUrl= %2Fhome %2Fhome.jsp` | `retUrl= %2F{!Account.Id}` | | DescriptionObjectName | Specifies the description of a transaction, using the name of a custom object. It must be an object name like *Account* or *Transaction__c*. This parameter requires *DescriptionObjectField* and *DescriptionObjectId*. | `DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId=001g000000T9wTR` | `DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId={!Account.Id}` | | DescriptionObjectField | Specifies the description of a transaction, using a field from a custom object. Must be a field in the object defined in *DescriptionObjectName*, like *Name* or *Description__c*. This parameter requires *DescriptionObjectName* and *DescriptionObjectId*. | `DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId=001g000000T9wTR` | `DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId={!Account.Id}` | | DescriptionObjectId | Specifies the description of a transaction, using a custom object's ID. Must be the ID of an object of the type defined in *DescriptionObjectName*. This parameter requires *DescriptionObjectName* and *DescriptionObjectField*. | `DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId=001g000000T9wTR` | `DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId={!Account.Id}` | | EmailMessageObjectName | Specifies the email message of a transaction, using the name of a custom object. Must be an object name like *Account* or *Transaction__c*. This parameter requires *EmailMessageObjectField* and *EmailMessageObjectId*. | `EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId=001g000000T9wTR` | `EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId={!Account.Id}` | | EmailMessageObjectField | Specifies the email message of a transaction, using a field from a custom object. Must be a field in the object defined in *EmailMessageObjectName,* like *Name* or *Description__c*. This parameter requires *EmailMessageObjectName* and *EmailMessageObjectId.* | `EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId=001g000000T9wTR` | `EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId={!Account.Id}` | | EmailMessageObjectId | Specifies the email message of a transaction, using the ID of a custom object. Must be the ID of an object of the type defined in *EmailMessageObjectName*. This parameter requires *EmailMessageObjectName* and *EmailMessageObjectField.* | `EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId=001g000000T9wTR` | `EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId={!Account.Id}` | | SignerX | X is a number from 1 to infinity. The value can be a lead ID, contact ID, user ID, or an email address. If an email address is provided, the parameters *SignerXFirstName* and *SignerXLastName* are required. | `Signer1=003g000000OLhpk or Signer1=support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe` | `Signer1={!Account.Main_Contact__c} or Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}` | | SignerXFirstName | Specifies the first name of the recipient at index X. It's available only for external email recipients. | `Signer1=support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe` | `Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}` | | SignerXLastName | Specifies the last name of the recipient at index X. It's available only for external email recipients. | `Signer1=support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe` | `Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}` | | SignerXPhone | Specifies the phone number of the recipient at index X. It's available only for external email recipients. | `Signer1=support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe& Signer1Phone=8675309` | `Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}& Signer1Phone={!Contact.Mobile}` | | SignerXLabel | Specifies the Recipient Label associated with the recipient at index X. Must be the ID of the recipient-label object in the related Convention (the default Convention or the one specified in *ConventionId*). | `Signer1=003g000000OLhpk& Signer1Label=a0Tg0000001uMIf` | `Signer1={!Contact.Id}& Signer1Label={!Contact.RecipientLabel__c}` | | SignerXAllowDelegation | Flag that determines if you will allow the original Recipient you identified to delegate someone else to sign the transaction on their behalf. Valid values are: *1* or *0*, *true* or *false*. If the value is *1* or *true*, the Recipient will be asked to enter the email address and full name of the delegate, plus an optional email message to be sent to the delegate. You will be notified of this change of Recipient, and will be CC’d on the email message (if sent). | `Signer1=003g000000OLhpk&Signer1AllowDelegation=true` | `Signer1={!Contact.Id}&Signer1AllowDelegation=1` | | SignerXAuthMethod | Flag that allows you to create a transaction automatically, using one of the following authentication methods: - Question and answer - SMS - Email If question and answer is selected as the authentication method, then the following additional parameters must be configured: - signerXQandAYQuestion – the authentication question - signerXQandAYTextAnswer – the correct answer to the authentication question. - signerXQandAYSFFieldAnswer –an alternative method of defining the answer. In this case, the answer comes from a specified field within the chosen type. For example, if using Contact as your Type, you could select any field within the Contact type, such as phone number. The Recipient would then enter their phone number , which is cross-referenced with the phone number field in their Contact type. Note that you cannot use this parameter if SignerX is of External Email type. Note also that you need to provide either signerXQandAYSFFieldAnswer or signerXQandAYTextAnswer, but you cannot provide both. - signerXQandAYMaskAnswer – determines whether or not the answer typed by the user should be masked while typing. Possible values are true and false. This parameter is optional and defaults to false. - Note that X is the number of recipients and Y is the number of questions (up to 2 questions are supported). | `Signer1=003g000000OLhpk&Signer1AuthMethod=sms` `Signer1=003g000000OLhpk&Signer1AuthMethod=qaRecipient` `1=003g000000OLhpk&Signer1AuthMethod=email` | `Signer1={!Contact.Id}&Signer1AuthMethod={!Contact.AuthenticationMethod__c}` | | AutoPrepare | Flag that determines if the *AutoPrepare* feature will be activated for a transaction if a Convention is specified. Valid values are: *1* or *0*, *true* or *false*. | `AutoPrepare=true` | `AutoPrepare={!Account.AutoPrepareTransaction__c} Insert={!Account.InsertValueInTransaction__c} ` | | Insert | Flag that determines if data from Salesforce will be auto-populated into a OneSpan Sign document when the document's transaction is being prepared. Valid values are: *1* or *0*, *true* or *false*. | `Insert=true` | `Insert={!Account.InsertValueInTransaction__c}` | | WriteBack | Flag that determines if a Salesforce field will be updated with data from a OneSpan Sign document when that document's transaction is completed. Valid values are: *1* or *0*, *true* or *false*. | `WriteBack=true` | `WriteBack={!Account.WriteValueInTransaction__c}` | | EnforceSigningOrder | Flag that determines if the *enforce signing order* condition is true or false. | `EnforceSigningOrder=true` | `EnforceSigningOrder={!Account.EnforceSigningOrder__c}` | | ParentId | ID of the parent object. To be stored in the *ParentId* text field. It automatically populates the parent type and the related lookup field if possible. | `ParentId=001g000000T9wTR` | `ParentId={!Account.Id}` | | enableReminders | Flag (true / false) that determines if the automatic-reminder feature is set for the transaction. | `enableReminders=true` | `enableReminders={!Account.RemindersEnabled__c}` | | sendReminderDays | Number of days before the first reminder is sent. | `sendReminderDays=2` | `sendReminderDays={!Account.SendReminderDays__c}` | | repeatReminderDays | Interval in days between successive reminders. | `repeatReminderDays=1` | `repeatReminderDays={!Account.RepeatReminders__c}` | | totalReminders | Maximum number of reminders to be sent. | `totalReminders=10` | `totalReminders={!Account.TotalReminders__c}` | | ChatterEnable | Flag (true / false) that determines if Chatter will be active on the transaction. | `ChatterEnable=true` | `ChatterEnable={!Account. ChatterEnable __c}` |