To download the full code sample see our Code Share site.

A transaction is the experience of a OneSpan Sign user as they review, accept, sign, and potentially download documents.

This topic will walk you through the process to create and send a transaction using the OneSpan Sign Java SDK.

Prerequisites

To complete these procedures you will need the following:

  • Eclipse IDE for Java EE Developers: You can download it from here.
  • OneSpan Sign's Java SDK: You can download it from our Community Portal. Or alternatively, you can import them from our Maven Repository by using the following commands:
    <dependency>
                <groupId>com.silanis.esl</groupId>
                <artifactId>sdk</artifactId>
                <version>11.21</version>
    </dependency>

How to create and configure a Java project

To create and configure Java project

  1. Open Eclipse by running eclipse.exe from the root Eclipse folder. Once it has started, open the Java perspective. You can do this by going to Windows > Open Perspective > Other > Java.
  2. Capture

  3. Once you have the Java perspective open, you should see the Package Explorer view on the left side of the screen. Right-click inside this window and go to New > Java Project. The follow window appears:

    Capture

  4. Name your project whatever you would like. For example, CreateAndSendPackage. Then click Next.
  5. On the Libraries tab, click Add External JAR. Navigate to the location that you saved your SDK to, and select the sdk jar-with-dependencies jar.
  6. Select Open. You will see that the SDK jar has been added to your build path.

    Capture

  7. Click Finish. Your new project has now been added to your Package Explorer view.

    Capture

  8. Expand the package by clicking on the arrow to the left, right-click on the src folder and go to New > Package. Enter a package name (for example, com.esignlive.example). Click Finish.

    Capture

  9. Create a new java file:
    1. Right-click on your new package in the Package Explorer and go to New > File.
    2. Enter a name for the file (for example, SimpleCreateAndSendPackage.java).
    3. Click Finish.
    4. Add a sample PDF file that you want to have signed to your project. You can use a simple copy and paste from your file system to your project in the package explorer.

    Your project should now look like this:

  10. Capture

The Code

In this section, the code will be broken down section by section. You can download the full sample code from the Developer Community Code Share, here.

How to connect

The following code lines define your connection information for OneSpan Sign.

public static final String API_KEY = "your_api_key";
public static final String API_URL = "https://sandbox.esignlive.com/api";    // Use https://apps.esignlive.com/api For Production

//Alternatively
public static final String CLIENT_APP_ID = "your_client_id";
public static final String CLIENT_APP_SECRET = "your_client_secret";
public static final String BASE_API_URL = "https://sandbox.esignlive.com";    // Use https://apps.esignlive.com For Production
public static final String API_URL = BASE_API_URL + "/api";    
			

API Keys

While API keys can be used with OneSpan Sign, we recommend that you use Client Apps instead. Clients Apps are more flexible and help reduce the number of potential security vulnerabilities.

Client apps provide the following benefits over API Keys:

  • With Client Apps access can be created, rotated, or revoked as needed. API Keys are fixed, and thus if you want to make any access changes you will need to contact our Support Team.

  • Multiple Client Apps can be used if you have multiple integrations configured. This helps to limit the scope of any fraudulent attack on your system. Conversely, only one API Key is provided for all integrations.

  • Client Apps use temporary tokens to allow API access, which are only available for a brief period of time. API Keys do not expire, and thus any breach will require you to contact our Support Team.

The API key may not be visible, depending on your environment and your account privileges. Only an account owner can view an API key.

To view your API key

  • In the API Key section of the API Key and Client Appspage, click the View icon.

By default, your API key is masked.

Client Apps

Before integrators can make requests via REST APIs or SDK functions, OneSpan Sign requires that users either register a Client Apps, or provide a secure API Key to authenticate the API calls. OneSpan recommends that you use Client Apps.

To register a Client App

You can authenticate REST API calls from within a user's system by providing the user with a secure but short-lived (e.g., 30-minute) API Token that can be used for authentication. This feature is called Client Apps. To enable it, you must contact our Support Team. Once this feature is enabled, third-party integrators will be able to connect to the OneSpan Sign API using these API Tokens.

This feature is not supported for OneSpan Sign connectors.

To create a Client App

  1. Click Admin > API Access.
  2. In the Authentication Settings page, use the left panel to select API Key and Client Apps.
  3. Click Add. A Create Client App sidebar appears.
  4. Enter a Name for the Client App.
  5. Click Create.
  6. Copy the Client ID and Secret codes that appear.
  7. Store the Client ID and Secret codes in a secure location.
  8. Click Done.

The Secret will no longer appear once you click Done. For your records. please copy this Secret to a secure location. Both the Client ID and Secret are used to retrieve the temporary API Token.

Next is the API_URL. If you’re using a Sandbox account, the correct URL is already in place. If you are using a Production account, find the corresponding URL in this guide.

How to create a Package

The following line of code creates a OneSpan Sign Client using the OneSpan Sign account’s Client Apps credentials or API Key and the appropriate API URL that you defined above.

EslClient eslClient = new EslClient(API_KEY, API_URL);

//Alternatively
EslClient eslClient = new EslClient(ApiTokenConfig.newBuilder()
		.clientAppId(CLIENT_APP_ID)
		.clientAppSecret(CLIENT_APP_SECRET)
		.baseUrl(BASE_API_URL)
		.tokenType(TokenType.OWNER)
		.build(), 
		BASE_API_URL + "/api", false, null, new Dictionary<string,string>());
			

The next block of code is where you actually create the document package. Within this block, you give your package a name.

DocumentPackage documentPackage = newPackageNamed("Test Package Java SDK")

Next, you will add two signers to the package. One being yourself and the other being the person you will send the package to. In this block, replace the email addresses and names (and optionally company and titles) with your test information. Set the Custom Id in the SDK to better identify your signer.

.withSigner(newSignerWithEmail("[email protected]")
		.withCustomId("Signer")                           //optional
		.withFirstName("SignerFirstName")
		.withLastName("SignerLastName") 
		.withCompany("ABC Company")                       //optional
		.withTitle("Applicant"))                          //optional
.withSigner(newSignerWithEmail("[email protected]")
		.withFirstName("YourFirstName")
		.withLastName("YourLastName"))

Now, you add the document you want to be signed and place the signature blocks for your signers. Again, remember to replace the sample values in this block with your test information. Optionally, setting Document and Signature Ids will help you better locate your signatures.

.withDocument(newDocumentWithName("sampleAgreement")
	.withId("document1")                              //optional
	.fromFile("your_file_path")
	.withSignature(signatureFor("[email protected]")
		.withId(new SignatureId("signature1"))    //optional
		.onPage(0)
		.atPosition(175, 165))
	.withSignature(signatureFor("[email protected]")
		.onPage(0)
		.atPosition(550, 165)))

Finally, you build your package using the following code:

.build();

Now that the document package is ready, access your OneSpan Sign Client, create your package, and send it to the signers. To do this, use the following code:

// Issue the request to the OneSpan Sign server to create the DocumentPackage
PackageId packageId = eslClient.createPackageOneStep(documentPackage);
 
// Send the package to be signed by the participants
eslClient.sendPackage(packageId);

Results

With your Java class completed, you can go ahead and execute your simple application. There are a few ways you can do this from Eclipse:

  • In the toolbar, select the Run button
  • From the menu bar, select Run > Run
  • In the Package Explorer right-click on your Java class and select Run As > Java Application.

If you check your OneSpan Sign Sandbox account Inbox, you will see that the package has been created and waiting for signatures.

To download the full code sample see our Code Share site.

This topic will walk you through the process of building a package using the OneSpan Sign .NET SDK. In this topic you will learn how to:

  • Download .NET SDK and Microsoft Visual Studio

  • Create and configure a C# project
  • Create and send a document package

Prerequisites

To continue you must have the following:

  • OneSpan Sign's .NET SDK: To download the most recent version of OneSpan Sign's .NET SDK, see Getting Started with SDKs.
  • Microsoft Visual Studio: This topic uses Microsoft Visual Studio. You can use something else, but everything in this guide will be described using Visual Studio. To download Microsoft Visual Studio see the Visual Studio Community. Ensure that you select .NET desktop development when installing.

How To Create a C# Project in Visual Studio

Before you create and send a package, you will need to create a Microsoft Visual Studio project.

To Create and Configure Your C# Project

  1. Launch Microsoft Visual Studio.
  2. Click Create a New Project.
  3. Select Blank Project and name it as you like. Once completed you will now see your project in the Solution Explorer.
  4. Click Tools > NuGet Package Manager > Package Manager Console.
  5. Enter the following command, where <version_number> is the version number of the OneSpan Sign's .NET SDK you downloaded earlier.
  6. Install-Package OneSpanSign.Sdk -Version <version_number>

You will now see this file in your project in the Solution Explorer.

The Code

In this section, the code will be broken down section by section. You can download the full sample code from the Developer Community Code Share, here.

How to connect

The first few lines of code define the libraries you will use.

using OneSpanSign.Sdk;
using OneSpanSign.Sdk.Builder;				
using System;
using System.IO;

The following code lines define your connection information for OneSpan Sign.

private static String API_URL = "https://sandbox.esignlive.com/api";    // Use https://apps.esignlive.com/api For Production
private static String API_KEY = "YOUR_API_KEY";

//Alternatively
private static String CLIENT_APP_ID = "your_client_id";
private static String CLIENT_APP_SECRET = "your_client_secret";
private static String BASE_API_URL = "https://sandbox.esignlive.com";    // Use https://apps.esignlive.com For Production
private static String API_URL = BASE_API_URL + "/api"; 
			

API Keys

While API keys can be used with OneSpan Sign, we recommend that you use Client Apps instead. Clients Apps are more flexible and help reduce the number of potential security vulnerabilities.

Client apps provide the following benefits over API Keys:

  • With Client Apps access can be created, rotated, or revoked as needed. API Keys are fixed, and thus if you want to make any access changes you will need to contact our Support Team.

  • Multiple Client Apps can be used if you have multiple integrations configured. This helps to limit the scope of any fraudulent attack on your system. Conversely, only one API Key is provided for all integrations.

  • Client Apps use temporary tokens to allow API access, which are only available for a brief period of time. API Keys do not expire, and thus any breach will require you to contact our Support Team.

The API key may not be visible, depending on your environment and your account privileges. Only an account owner can view an API key.

To view your API key

  • In the API Key section of the API Key and Client Appspage, click the View icon.

By default, your API key is masked.

Client Apps

Before integrators can make requests via REST APIs or SDK functions, OneSpan Sign requires that users either register a Client Apps, or provide a secure API Key to authenticate the API calls. OneSpan recommends that you use Client Apps.

To register a Client App

You can authenticate REST API calls from within a user's system by providing the user with a secure but short-lived (e.g., 30-minute) API Token that can be used for authentication. This feature is called Client Apps. To enable it, you must contact our Support Team. Once this feature is enabled, third-party integrators will be able to connect to the OneSpan Sign API using these API Tokens.

This feature is not supported for OneSpan Sign connectors.

To create a Client App

  1. Click Admin > API Access.
  2. In the Authentication Settings page, use the left panel to select API Key and Client Apps.
  3. Click Add. A Create Client App sidebar appears.
  4. Enter a Name for the Client App.
  5. Click Create.
  6. Copy the Client ID and Secret codes that appear.
  7. Store the Client ID and Secret codes in a secure location.
  8. Click Done.

The Secret will no longer appear once you click Done. For your records. please copy this Secret to a secure location. Both the Client ID and Secret are used to retrieve the temporary API Token.

Next is the API_URL. If you’re using a Sandbox account, the correct URL is already in place. If you are using a Production account, you should use the commented out URL.

OssClient ossClient = new OssClient(API_KEY, API_URL);
			
//Alternatively
OssClient ossClient = new OssClient(new ApiTokenConfig {
	ClientAppId = CLIENT_APP_ID,
	ClientAppSecret = CLIENT_APP_SECRET,
	BaseUrl = BASE_API_URL,
	TokenType = ApiTokenType.OWNER
},   
BASE_API_URL + "/api", false, null, new Dictionary<string, string>());
			

In the next line, you create a FileStream and read in the file you want to upload with your package. Make sure you replace the placeholder PATH_TO_YOUR_PDF text with the location of your PDF file.

FileStream fs = File.OpenRead("PATH_TO_YOUR_PDF");

The next block of code is where you actually create the document package. Within this block, you give your package a name.

DocumentPackage superDuperPackage = PackageBuilder
	.NewPackageNamed("Test Package .NET")
	.WithSettings(DocumentPackageSettingsBuilder.NewDocumentPackageSettings())

Then, the signers are added to the package.

.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
			.WithFirstName("Signer First Name")
			.WithLastName("Signer Last Name")
			.WithCustomId("Signer"))
.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
			.WithFirstName("Your First Name")
			.WithLastName("Your Last Name"))

Next, the document is added, including signature boxes for your signers.

.WithDocument(DocumentBuilder.NewDocumentNamed("sampleAgreement")
			.FromStream(fs, DocumentType.PDF)
			.WithSignature(SignatureBuilder
				.SignatureFor("[email protected]")
				.OnPage(0)
				.AtPosition(175, 165))
			.WithSignature(SignatureBuilder
				.SignatureFor("[email protected]")
				.OnPage(0)
				.AtPosition(550, 165))
			)

With the package completely defined, you can now build the package and send it.

.Build();
 
PackageId packageId = ossClient.CreatePackageOneStep(superDuperPackage);
ossClient.SendPackage(packageId);

Results

Execute this code by selecting Start from the toolbar. After doing this, you should be able to log into OneSpan Sign account and view the package you just created.

To download the full code sample see our Code Share site.

This topic will walk you through the process to create and send a transaction using the OneSpan Sign Java REST API.

In this example a minimum payload is used, where two signers, one document, and one signature per signer are added to the package.

For a complete description of each field and other optional attributes, see Request Payload Table. You can also refer to the Interactive API for more information.

HTTP Request

POST /api/packages

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Accept: application/json
Content-Type: multipart/form-data

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"	
{
	"roles":[
		{
			"id":"Role1",
			"signers":[
				{
					"email":"[email protected]",
					"firstName":"1.firstname",
					"lastName":"1.lastname",
					"company":"OneSpan Sign"
				}
			]
		},
		{
			"id":"Role2",
			"signers":[
				{
					"email":"[email protected]",
					"firstName":"2.firstname",
					"lastName":"2.lastname",
					"company":"OneSpan Sign"
			}
		]
	}
],
				
"documents":[
	{
		"approvals":[
			{
				"role":"Role1",
				"fields":[
					{
						"page":0,
						"top":100,
						"subtype":"FULLNAME",
						"height":50,
						"left":100,
						"width":200,
						"type":"SIGNATURE"
					}
				]
			},
		{
				"role":"Role2",
				"fields":[
					{
						"page":0,
						"top":300,
						"subtype":"FULLNAME",
						"height":50,
						"left":100,
						"width":200,
						"type":"SIGNATURE"
					}
				]
			}
	
		],
		"name":"Test Document"
	}
],
"name":"Example Package",
"type":"PACKAGE",
"language":"en",
"emailMessage":"",
"description":"New Package",
"autocomplete":true,
"status":"SENT"

}
------WebKitFormBoundary1bNO60n7FqP5WO4t--
			

Response Payload

{
"id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

Prerequisites

To complete these procedures you will need the following:

  • Eclipse IDE for Java EE Developers: You can download it from here.

How to Create and Configure a Java Project

To begin, you need to create and configure a Java project.

To create and configure Java project

  1. Open Eclipse by running eclipse.exe from the root Eclipse folder. Once it has started, open the Java perspective. You can do this by going to Windows > Open Perspective > Other > Java.
  2. Capture

  3. Once you have the Java perspective open, you should see the Package Explorer view on the left side of the screen. Right-click inside this window and go to New > Java Project. The follow window appears:

    Capture

  4. Name your project whatever you would like. For example, CreateAndSendPackage.
  5. Click Finish. Your new project has now been added to your Package Explorer view.

    Capture

  6. Expand the package by clicking on the arrow to the left, right-click on the src folder and go to New > Package. Enter a package name (for example, com.esignlive.example). Click Finish.

    Capture

  7. Create a new java file:
    1. Right-click on your new package in the Package Explorer and go to New > File.
    2. Enter a name for the file (for example, SimpleCreateAndSendPackage.java).
    3. Click Finish.
    4. Add a sample PDF file that you want to have signed to your project. You can use a simple copy and paste from your file system to your project in the package explorer.

    Your project should now look like this:

  8. Capture

The Code

In this section, the code will be broken down section by section. You can download the full sample code from the Developer Community Code Share, here.

How to connect

The following code lines define your connection information for OneSpan Sign.

string apiKey = "YOUR_API_KEY";
string url = "https://sandbox.esignlive.com/api/packages";

API Keys

While API keys can be used with OneSpan Sign, we recommend that you use Client Apps instead. Clients Apps are more flexible and help reduce the number of potential security vulnerabilities.

Client apps provide the following benefits over API Keys:

  • With Client Apps access can be created, rotated, or revoked as needed. API Keys are fixed, and thus if you want to make any access changes you will need to contact our Support Team.

  • Multiple Client Apps can be used if you have multiple integrations configured. This helps to limit the scope of any fraudulent attack on your system. Conversely, only one API Key is provided for all integrations.

  • Client Apps use temporary tokens to allow API access, which are only available for a brief period of time. API Keys do not expire, and thus any breach will require you to contact our Support Team.

The API key may not be visible, depending on your environment and your account privileges. Only an account owner can view an API key.

To view your API key

  • In the API Key section of the API Key and Client Appspage, click the View icon.

By default, your API key is masked.

Client Apps

Before integrators can make requests via REST APIs or SDK functions, OneSpan Sign requires that users either register a Client Apps, or provide a secure API Key to authenticate the API calls. OneSpan recommends that you use Client Apps.

To register a Client App

You can authenticate REST API calls from within a user's system by providing the user with a secure but short-lived (e.g., 30-minute) API Token that can be used for authentication. This feature is called Client Apps. To enable it, you must contact our Support Team. Once this feature is enabled, third-party integrators will be able to connect to the OneSpan Sign API using these API Tokens.

This feature is not supported for OneSpan Sign connectors.

To create a Client App

  1. Click Admin > API Access.
  2. In the Authentication Settings page, use the left panel to select API Key and Client Apps.
  3. Click Add. A Create Client App sidebar appears.
  4. Enter a Name for the Client App.
  5. Click Create.
  6. Copy the Client ID and Secret codes that appear.
  7. Store the Client ID and Secret codes in a secure location.
  8. Click Done.

The Secret will no longer appear once you click Done. For your records. please copy this Secret to a secure location. Both the Client ID and Secret are used to retrieve the temporary API Token.

How to create a Package

After that, you will see several variables being set that are used in the creation of the POST call, like the form boundary value and the file you plan to upload.

String charset = "UTF-8";
File uploadFile1 = new File("C:/Eclipse/workspace_442/CreateAndSendPackage/sampleAgreement.pdf");
String boundary = Long.toHexString(System.currentTimeMillis()); // Generate a random value for the form boundary
String CRLF = "\r\n"; // Line separator used in multipart/form-data

The next line is the JSON string that defines your package. Typically, you will probably build your JSON string dynamically versus having a giant static string, like this. However, this example can be used to provide a good representation of the structure of the JSON you will need in order to create your package properly. Note that many properties are left empty in the string as they are not necessary for package creation. They are there to give you a list of options that are available and how they are passed in the JSON.

The first part of the package JSON string is the roles object. Inside this, you can set items like the id, company, first name, last name, email, and name to customize your signer roles. Some of the other notable settings would be email message, title, and delivery.

string jsonString = "{";
		jsonString += "\"roles\":[{\"id\":\"Role1\",\"signers\":[{\"email\":\"[email protected]\",\"firstName\":\"1.firstname\",\"lastName\":\"1.lastname\",\"company\":\"OneSpan Sign\"}]},{\"id\":\"Role2\",\"signers\":[{\"email\":\"[email protected]\",\"firstName\":\"2.firstname\",\"lastName\":\"2.lastname\",\"company\":\"OneSpan Sign\"}]}],";

The next section of the package JSON string is the documents object. Inside this, you will set items like the name and the approvals (signature blocks). In the approvals, the main items to set would be the type, subtype, role, page, and the location settings. These will define the signatures required in each document.

Finally, the last few settings of the package JSON string that you will want to note are the name, type, status, emailMessage, and autoComplete. Next, you will define the connection on which you will send your request. The first line opens the connection to the request URL. Notice that the rest of the URL for the particular request that is being made is added to the base URL, here. The rest sets up the request properties and creates the OutputStream and PrintWriter for communicating the request payload with OneSpan Sign.

HttpsURLConnection connection = null;
URL url = new URL(requestURL);
connection = (HttpsURLConnection) url.openConnection();
connection.setDoOutput(true);
connection.setDoInput(true);
connection.setRequestMethod("POST");				
connection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
connection.setRequestProperty("Authorization", "Basic " + apiKey);
connection.setRequestProperty("Accept", "application/json; esl-api-version=11.0");
OutputStream output = connection.getOutputStream();
PrintWriter writer = new PrintWriter(new OutputStreamWriter(output, charset), true);

Inside the try block, the actual multipart form is created. In the code below you can see how the boundary, form part descriptors, and content are added in each portion of the form.

// Add pdf file.
writer.append("--" + boundary).append(CRLF);
writer.append("Content-Disposition: form-data; name=\"file\"; filename=\"" + uploadFile1.getName() + "\"").append(CRLF);
writer.append("Content-Type: " + URLConnection.guessContentTypeFromName(uploadFile1.getName())).append(CRLF);
writer.append(CRLF).flush();
Files.copy(uploadFile1.toPath(), output);
output.flush();
writer.append(CRLF).flush();
                 
// add json payload
writer.append("--" + boundary).append(CRLF);
writer.append("Content-Disposition: form-data; name=\"payload\"").append(CRLF);
writer.append("Content-Type: application/json; charset=" + charset).append(CRLF);
writer.append(CRLF).append(jsonContent).append(CRLF).flush();
 
// End of multipart/form-data.
writer.append("--" + boundary + "--").append(CRLF).flush();

Finally, you will make the POST call, passing your form to OneSpan Sign, which creates your document package. The response code and response content are printed out to the console.

int responseCode = ((HttpURLConnection) connection).getResponseCode();
System.out.println(responseCode);
if (responseCode == 200) {
	// get and write out response
	BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
	String inputLine;
	StringBuffer response = new StringBuffer();
	while ((inputLine = in.readLine()) != null) {
	response.append(inputLine);
	}
	in.close();
	/ print result
	System.out.println(response.toString());
} else {
	// get and write out response
	BufferedReader in = new BufferedReader(new InputStreamReader(connection.getErrorStream()));
	String inputLine;
	StringBuffer response = new StringBuffer();
	while ((inputLine = in.readLine()) != null) {
	response.append(inputLine);
	}
	in.close();
	// print result
	System.out.println(response.toString());
}

Results

If everything with your REST call is correct, you should get a package ID returned as your response:

Capture

If you log in to your OneSpan Sign account, you can see the package has been created as defined in your request.

Request Payload Table

Property Type Editable Required Default Sample Values Reference
roles Signer Management
id string Yes No n/a Signer1
name string Yes No n/a Signer1
emailMessage array Yes No n/a check reference Email Message
reassign boolean Yes No 0 true/false Change Signer
attachmentRequirements array Yes No n/a check reference Attachment Requirements
index string Yes No 0 0/1/2/3 Signer Workflow
type string Yes No SIGNER SIGNER / SENDER
signers
id string Yes No n/a Signer1
email string Yes Yes n/a [email protected]
firstName string Yes Yes n/a Patty
lastName string Yes Yes n/a Galant
company string Yes No n/a Acme Inc.
title string Yes No null Managing Director
group array Yes No n/a check reference Groups
language string Yes No n/a en/fr/es/… Configure Package Language
signature
textual string No No null
handdrawn string Yes No n/a AQAAAMkGIVM7tmRJzS2cANoDcyT0ASABAwA=  
delivery array Yes No n/a check reference Deliver Signed Documents By Email
knowledgeBasedAuthentication array Yes No n/a check reference Signer Authentication
auth array Yes No n/a check reference Signer Authentication
documents Document Management
description string Yes No n/a Test document1 description
id string Yes No n/a document1
data array Yes No n/a check reference Document Attributes
approvals Signatures
role string Yes Yes n/a Signer1
id string Yes No n/a approval1
optional boolean Yes No 0 true/false Optional Signature
enforceCaptureSignature boolean Yes No 0 true/false Enforce Capture Signature
fields array Yes No n/a check reference Fields (also see Text Anchors)
name string Yes No n/a document 1
extract boolean Yes No 0 true/false Document Extraction/ Text Tag/ Position Extraction
extractionTypes array Yes No n/a ["TEXT_TAGS","ACROFIELDS"] Document Extraction/ Text Tag
fields array Yes No n/a check reference Field Injection
name string Yes No n/a document1
settings array Yes No n/a check reference Signer Experience Customization
sender Create a Package on Behalf of Another User
lastName string Yes No n/a Smith
firstName string Yes No n/a Bob
email string Yes No n/a [email protected](who is an sender under your main account)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
name string Yes No n/a Package created from template through REST API
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
description string Yes No n/a Package created with the OneSpan Sign REST API
language string Yes No en en / fr / es … Configure Package Language
visibility string Yes No ACCOUNT ACCOUNT / SENDER
autoComplete boolean Yes No 1 true / false
data array Yes No n/a check reference Package Attribute
due string Yes No null 08-26-17
notarized boolean Yes No 0 true/false (check reference, only use when notarization) eNotary
notaryRoleId string Yes No n/a Signer1 (check reference, only use when notarization) eNotary
emailMessage string Yes No n/a This message should be delivered to all signers

To download the full code sample see our Code Share site.

This topic will walk you through the process to create and send a transaction using .NET REST.

In this example a minimum payload is used, where two signers, one document, and one signature per signer are added to the package.

For a complete description of each field and other optional attributes, see Request Payload Table. You can also refer to the Interactive API for more information.

HTTP Request

POST /api/packages

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Accept: application/json
Content-Type: multipart/form-data

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf" Content-Type: application/pdf %PDF-1.5 %µµµµ 1 0 obj <>>> endobj.... ------WebKitFormBoundary1bNO60n7FqP5WO4t Content-Disposition: form-data; name="payload" { "roles":[ { "id":"Role1", "signers":[ { "email":"[email protected]", "firstName":"1.firstname", "lastName":"1.lastname", "company":"OneSpan Sign" } ] }, { "id":"Role2", "signers":[ { "email":"[email protected]", "firstName":"2.firstname", "lastName":"2.lastname", "company":"OneSpan Sign" } ] } ], "documents":[ { "approvals":[ { "role":"Role1", "fields":[ { "page":0, "top":100, "subtype":"FULLNAME", "height":50, "left":100, "width":200, "type":"SIGNATURE" } ] }, { "role":"Role2", "fields":[ { "page":0, "top":300, "subtype":"FULLNAME", "height":50, "left":100, "width":200, "type":"SIGNATURE" } ] } ], "name":"Test Document" } ], "name":"Example Package", "type":"PACKAGE", "language":"en", "emailMessage":"", "description":"New Package", "autocomplete":true, "status":"SENT" } ------WebKitFormBoundary1bNO60n7FqP5WO4t--

Response Payload

{
	"id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

How to Create and Configure a .NET Project

This topic will walk you through the process to check the status of a transaction and to download any documents using the OneSpan Sign .NET SDK. In this topic you will learn how to:

  • Download Microsoft Visual Studio

  • Create and configure a C# project
  • Create and send a document package

Prerequisites

To complete these procedures you will need the following:

  • Microsoft Visual Studio: This topic uses Microsoft Visual Studio. You can use something else, but everything in this guide will be described using Visual Studio. To download Microsoft Visual Studio see the Visual Studio Community. Ensure that you select .NET desktop development when installing.

How To Create a C# Project in Visual Studio

Before you create and send a package, you will need to create a Microsoft Visual Studio project.

To Create and Configure Your C# Project in Visual Studio

  1. Launch Microsoft Visual Studio.
  2. Click Create a New Project.
  3. Select blank project and name it as you like. Once completed you will now see your project in the Solution Explorer.

You will now see this file in your project in the Solution Explorer.

The Code

This guide will breakdown the code section by section. You can download to full sample code from the Code Share site.

How to connect

The following code lines define your connection information for OneSpan Sign.

string apiKey = "YOUR_API_KEY";
string url = "https://sandbox.esignlive.com/api";

API Keys

While API keys can be used with OneSpan Sign, we recommend that you use Client Apps instead. Clients Apps are more flexible and help reduce the number of potential security vulnerabilities.

Client apps provide the following benefits over API Keys:

  • With Client Apps access can be created, rotated, or revoked as needed. API Keys are fixed, and thus if you want to make any access changes you will need to contact our Support Team.

  • Multiple Client Apps can be used if you have multiple integrations configured. This helps to limit the scope of any fraudulent attack on your system. Conversely, only one API Key is provided for all integrations.

  • Client Apps use temporary tokens to allow API access, which are only available for a brief period of time. API Keys do not expire, and thus any breach will require you to contact our Support Team.

The API key may not be visible, depending on your environment and your account privileges. Only an account owner can view an API key.

To view your API key

  • In the API Key section of the API Key and Client Appspage, click the View icon.

By default, your API key is masked.

Client Apps

Before integrators can make requests via REST APIs or SDK functions, OneSpan Sign requires that users either register a Client Apps, or provide a secure API Key to authenticate the API calls. OneSpan recommends that you use Client Apps.

To register a Client App

You can authenticate REST API calls from within a user's system by providing the user with a secure but short-lived (e.g., 30-minute) API Token that can be used for authentication. This feature is called Client Apps. To enable it, you must contact our Support Team. Once this feature is enabled, third-party integrators will be able to connect to the OneSpan Sign API using these API Tokens.

This feature is not supported for OneSpan Sign connectors.

To create a Client App

  1. Click Admin > API Access.
  2. In the Authentication Settings page, use the left panel to select API Key and Client Apps.
  3. Click Add. A Create Client App sidebar appears.
  4. Enter a Name for the Client App.
  5. Click Create.
  6. Copy the Client ID and Secret codes that appear.
  7. Store the Client ID and Secret codes in a secure location.
  8. Click Done.

The Secret will no longer appear once you click Done. For your records. please copy this Secret to a secure location. Both the Client ID and Secret are used to retrieve the temporary API Token.

Next is the API_URL. If you’re using a Sandbox account, the correct URL is already in place. If you are using a Production account, you should use the commented out URL.

How to create a Package

The next line is the JSON string that defines your package. Typically, you will probably build your JSON string dynamically versus having a giant static string, like this. This is to give a good representation of the structure of the JSON in order to create your package properly. Many properties are purposely left empty in the string that are not necessary for creation so you can see some of the other options that are available and how they are passed in the JSON.

The first part of the package JSON string is the roles object. Inside this, you can set items like the id, company, first name, last name, email, and name to customize your signer roles. Some of the other notable settings would be email message, title, and delivery.

{
	"roles":[
		{
			"id":"Role1",
			"signers":[
				{
					"email":"[email protected]",
					"firstName":"1.firstname",
					"lastName":"1.lastname",
				"company":"OneSpan Sign"
				}
			]
		},

The next section of the package JSON string is the documents object. Inside this, you will set items like the name and the approvals (signature blocks).

 "documents":[
	{
		"approvals":[
			{
				"role":"Role1",
				"fields":[
					{
						"page":0,
						"top":100,
						"subtype":"FULLNAME",
						"height":50,
						"left":100,
						"width":200,
						"type":"SIGNATURE"
				}
			]
		},

In the approvals, the main items to set would be the type, subtype, role, page, and the location settings. These will define the signatures required in each document.

            jsonString += "\"documents\":[{\"approvals\":[{\"role\":\"Role1\",\"fields\":[{\"page\":0,\"top\":100,\"subtype\":\"FULLNAME\",\"height\":50,\"left\":100,\"width\":200,\"type\":\"SIGNATURE\"}]},{\"role\":\"Role2\",\"fields\":[{\"page\":0,\"top\":300,\"subtype\":\"FULLNAME\",\"height\":50,\"left\":100,\"width\":200,\"type\":\"SIGNATURE\"}]}],\"name\":\"Test Document\"}],";
			

Finally, the last few settings of the package JSON string that you will want to note are the name, type, status, emailMessage, and autoComplete. In this example, status is set to SENT. This will send the package and notify the signers. If you want to save this package as a draft, make the value DRAFT, instead.

 jsonString += "\"name\":\"Example Package\",\"type\":\"PACKAGE\",\"language\":\"en\",\"emailMessage\":\"\",\"description\":\"New Package\",\"autocomplete\":true,\"status\":\"SENT\"";
jsonString += "}";

The next line of the code will take your JSON string and make the StringContent object that you will pass as the payload in your REST API command.

StringContent jsonContent = new StringContent(jsonString, Encoding.UTF8, "application/json");

The next couple lines will read in your PDF file and use that to create your file ByteArrayContent object for your REST call. Be sure to change the placeholder to the path of your file.

byte[] fileByteArray = File.ReadAllBytes("PATH_TO_YOUR_PDF.pdf");
			ByteArrayContent content = new ByteArrayContent(fileByteArray);

The next several lines define the content disposition header of the pdf file content object.

content.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data");
content.Headers.ContentDisposition.Name = "\"file\"";
content.Headers.ContentDisposition.FileName = "\"NAME_OF_YOUR_FILE.pdf\"";
content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");

The next block of code is where you create your multipart form and add your content objects created above to pass with your REST call. Be sure to set the file name.

MultipartFormDataContent form = new MultipartFormDataContent();
form.Add(content, "\"file\"", "\"NAME_OF_YOUR_FILE.pdf\"");
form.Add(jsonContent, "\"payload\"");

Next, you will create the HttpClient that you will use to make your POST request and set the appropriate header authorization and accept values.

HttpClient myClient = new HttpClient();
myClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", apiKey);
myClient.DefaultRequestHeaders.Add("Accept", "application/json");

Finally, you will make the POST call, passing your form to OneSpan Sign, creating your document package. The Debug line will display the result to the debug output console.

var response = myClient.PostAsync(new Uri(url) + "/packages/", form).Result;
Debug.WriteLine(response.Content.ReadAsStringAsync().Result);

Results

If everything with your REST call is correct, you should get a package id returned as your response, like this one:

Capture

If you log in to your OneSpan Sign account, you can see the package has been created as defined in your request:

Request Payload Table

Property Type Editable Required Default Sample Values Reference
roles Signer Management
id string Yes No n/a Signer1
name string Yes No n/a Signer1
emailMessage array Yes No n/a check reference Email Message
reassign boolean Yes No 0 true/false Change Signer
attachmentRequirements array Yes No n/a check reference Attachment Requirements
index string Yes No 0 0/1/2/3 Signer Workflow
type string Yes No SIGNER SIGNER / SENDER
signers
id string Yes No n/a Signer1
email string Yes Yes n/a [email protected]
firstName string Yes Yes n/a Patty
lastName string Yes Yes n/a Galant
company string Yes No n/a Acme Inc.
title string Yes No null Managing Director
group array Yes No n/a check reference Groups
language string Yes No n/a en/fr/es/… Configure Package Language
signature
textual string No No null
handdrawn string Yes No n/a AQAAAMkGIVM7tmRJzS2cANoDcyT0ASABAwA=  
delivery array Yes No n/a check reference Deliver Signed Documents By Email
knowledgeBasedAuthentication array Yes No n/a check reference Signer Authentication
auth array Yes No n/a check reference Signer Authentication
documents Document Management
description string Yes No n/a Test document1 description
id string Yes No n/a document1
data array Yes No n/a check reference Document Attributes
approvals Signatures
role string Yes Yes n/a Signer1
id string Yes No n/a approval1
optional boolean Yes No 0 true/false Optional Signature
enforceCaptureSignature boolean Yes No 0 true/false Enforce Capture Signature
fields array Yes No n/a check reference Fields (also see Text Anchors)
name string Yes No n/a document 1
extract boolean Yes No 0 true/false Document Extraction/ Text Tag/ Position Extraction
extractionTypes array Yes No n/a ["TEXT_TAGS","ACROFIELDS"] Document Extraction/ Text Tag
fields array Yes No n/a check reference Field Injection
name string Yes No n/a document1
settings array Yes No n/a check reference Signer Experience Customization
sender Create a Package on Behalf of Another User
lastName string Yes No n/a Smith
firstName string Yes No n/a Bob
email string Yes No n/a [email protected](who is an sender under your main account)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
name string Yes No n/a Package created from template through REST API
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
description string Yes No n/a Package created with the OneSpan Sign REST API
language string Yes No en en / fr / es … Configure Package Language
visibility string Yes No ACCOUNT ACCOUNT / SENDER
autoComplete boolean Yes No 1 true / false
data array Yes No n/a check reference Package Attribute
due string Yes No null 08-26-17
notarized boolean Yes No 0 true/false (check reference, only use when notarization) eNotary
notaryRoleId string Yes No n/a Signer1 (check reference, only use when notarization) eNotary
emailMessage string Yes No n/a This message should be delivered to all signers

To download the full code sample see our Code Share site.

This guide will walk you through the process to create and send a document package (transaction in the new UI) with the OneSpan Sign APEX SDK, including, downloading the APEX SDK, and creating an APEX class.

Prerequisites

To complete these procedures you will need the following:

  • APEX SDK: Before you can use the APEX SDK, you will need to download it. You can do this by clicking here.
  • A Salesforce Developer Account: For this guide, you will need a Salesforce developer account. You can register for free by clicking here.

Create and Send a Package

Now that you have all of the essentials for completing the guide, you can go create and send a package.

Installing and Configuring the SDK

The SDK can be installed using the Deploy to Salesforce button.

Configuring your connection settings

After installing in your Sandbox or Developer organization, you will need to configure the connection settings by creating an entry in Custom Settings. Ensure that you have an entry with the API name OneSpan Sign Connection Settings in the organization and it has the following fields in it:

  • Endpoint__c
  • API_Key__c

Capture

Once you have the Custom Setting in place, you will need to ensure that you have a record with a name as Main. If you don’t have this record in the Custom Settings, you can add it.

To add a custom setting

  1. Navigate to the Custom Setting Details page
  2. Click Manage.
  3. Click New and enter the following:
    • Name: Main
    • Api Key: Your API Key
    • Endpoint: Enter your instance endpoint with /api appended to the end. For example, https://sandbox.esignlive.com/api
  4. Click Save.

Capture

Adding a Remote Site Endpoint

In order for the calls to go through from Salesforce, you will need to add the remote site endpoint. This is the same endpoint used when creating a Custom Setting, only without the /api appended onto the end. This will need to be added to the Remote Site Settings of the Salesforce organization from which you intend to use the SDK. Once you add the Remote Site, ensure that it is marked as Active, as shown below.

Capture

The Code

In this section, the code below will be broken down section by section.

public class OssCreatePackage{
 
	public void createPackage() {
	//Create OSS client
	OneSpanSDK sdk = new OneSpanSDK();
         
	//Create package
	OneSpanAPIObjects.Package_x pkg = new OneSpanAPIObjects.Package_x();
	pkg.name = 'Example Package Using APEX SDK1 - ' + Datetime.now().format();
         
	String packageId = sdk.createPackage(pkg);
	System.debug('PackageId: ' + packageId);
        
	//Add Signer
	String roleResponse = sdk.addRole('John', 'Smith', '[email protected]', packageId);
         
	//Add Document
	StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'testdoc1' LIMIT 1];
	Map<String,Blob> doc = new Map<String,Blob>();
	doc.put('Sample Document', sr.Body);
         
	OneSpanAPIObjects.Document document = new OneSpanAPIObjects.Document();
	document.name = 'Sample Contract';
	document.id = 'document1';
         
	sdk.createDocuments(packageId, document, doc);
	//Add Signature
	Map<String,Object> role = (Map<String,Object>)JSON.deserializeUntyped(roleResponse);
	String roleId = (String)(role.get('id'));
         
	OneSpanAPIObjects.Field field = new OneSpanAPIObjects.Field();
	field.left = 208;
	field.width = 200;
	field.height = 50;
	field.top = 518;
	field.page = 0;
	field.subtype = 'CAPTURE';
	field.type = 'SIGNATURE';
        
	List<OneSpanAPIObjects.Field> fields = new List<OneSpanAPIObjects.Field>();
	fields.add(field);
         
	OneSpanAPIObjects.Approval approval = new OneSpanAPIObjects.Approval();
	approval.fields = fields;
	approval.role = roleId;
         
	String signatureResponse = sdk.addSignature(packageId, 'document1', approval);
         
	//Send package
	pkg.status = OneSpanAPIObjects.PackageStatus.SENT;
         
	sdk.updatePackage(pkg, packageId);     
	}
}
			

The first line creates your OneSpan Sign client, using the OneSpan Sign API Key and the appropriate API URL that you defined in Installing and Configuring the SDK.

OneSpanSDK sdk = new OneSpanSDK();

The next block of code is where you create the document package. Within this block, you give your package a name.

        OneSpanAPIObjects.Package_x pkg = new OneSpanAPIObjects.Package_x();
	pkg.name = 'Example Package Using APEX SDK1 - ' + Datetime.now().format();
         
	String packageId = sdk.createPackage(pkg);
	System.debug('PackageId: ' + packageId);
			

Next, one signer is added to the package. This is the person you will send the package to for signing. In this block, you will replace the email address and name with your test information.

String roleResponse = sdk.addRole('John', 'Smith', '[email protected]', packageId);

Now, you add your document to be signed and also place the signature block for your signer. Again, remember to replace the sample values in this block with your test information.

//Add Document
	StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'testdoc1' LIMIT 1];
	Map<String,Blob> doc = new Map<String,Blob>();
	doc.put('Sample Document', sr.Body);
         
	OneSpanAPIObjects.Document document = new OneSpanAPIObjects.Document();
	document.name = 'Sample Contract';
	document.id = 'document1';
        
	sdk.createDocuments(packageId, document, doc);
	//Add Signature
	Map<String,Object> role = (Map<String,Object>)JSON.deserializeUntyped(roleResponse);
	String roleId = (String)(role.get('id'));
         
	OneSpanAPIObjects.Field field = new OneSpanAPIObjects.Field();
	field.left = 208;
	field.width = 200;
	field.height = 50;
	field.top = 518;
	field.page = 0;
	field.subtype = 'CAPTURE';
	field.type = 'SIGNATURE';
         
	List<OneSpanAPIObjects.Field> fields = new List<OneSpanAPIObjects.Field>();
	fields.add(field);
         
	OneSpanAPIObjects.Approval approval = new OneSpanAPIObjects.Approval();
	approval.fields = fields;
	approval.role = roleId;
         
	String signatureResponse = sdk.addSignature(packageId, 'document1', approval);
			

In this example, we added a pdf to the Static Resources in your Salesforce Developer account and read it as a blob type.

Capture

Now that your package is ready, you use your OneSpan Sign client to send it to the signer.

        //Send package
	pkg.status = OneSpanAPIObjects.PackageStatus.SENT;
         
	sdk.updatePackage(pkg, packageId);     
			

Results

With your APEX class completed, you can go ahead and execute it. Open up your Developer Console and press Ctrl + E to launch the Execute Anonymous Window. Type in:

new OssCreatePackage.createPackage();

And hit Execute.

You can see your package ID printed in debug console:

Capture

If you check your OneSpan Sign Sandbox account Inbox, you will see that the package has been created and waiting for signature.