1. Creating and Sending a Package

This guide shows you how to create and send your first document package.

This quick start guide will cover how to create and send a document package (transaction in the new UI) with the OneSpan Sign REST API. If you do not have a Sandbox account, see the Web UI guide for how you can get signed up.

The REST API

Below is the REST API for creating and sending a package. We used a basically minimum payload as an example where 2 signers, 1 document and 1 signature per signer are added to the package.
For a complete description of each field and other optional attributes, take a look at the JSON Properties section at the end of the guide.
You can find a complete description of each field and all optional attributes in JSON Properties section at the end of the guide. And also refer to the JSON Schema Document for more information.

HTTP Request
POST /api/packages

HTTP Headers
Authorization: Basic api_key
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":"signer1@mailinator.com",
               "firstName":"1.firstname",
               "lastName":"1.lastname",
               "company":"OneSpan Sign"
            }
         ]
      },
      {
         "id":"Role2",
         "signers":[
            {
               "email":"signer2@mailinator.com",
               "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="
}

Configuration

Before you can get started, you will need to set up your environment. This guide uses C# and Microsoft Visual Studio. Create a project (e.g. “CreateAndSendPackageREST”) and a .cs file (e.g “CreateAndSendPackageREST.cs”). If you need help getting this set up, see the .NET SDK guide (you can ignore the .NET SDK portion and skip to the “Downloading Microsoft Visual Studio” and “Create and Configure Your C# Project” sections) for more detailed instructions.

The Code

This guide will breakdown the code section by section. You can download to full sample code from the Developer Community Code Share, here.

In the first couple lines, the connection info for your OneSpan Sign connection is defined. If you’re using the production environment, use the url https://apps.esignlive.com/api. Make sure you replace the placeholder text with your API_KEY. You can find this value in the ACCOUNT page when signed into your OneSpan Sign account.

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

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”.

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”. 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.

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);

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:

Capture

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s) 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 patty.galant@mailinator.com
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/…
signature
textual string No No null
handdrawn string Yes No n/a AQAAAMkGIVM7tmRJzS2cANoDcyT0ASABAwA= Signature Import Tool
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 Signing Ceremony 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 bobsmith@email.com(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

This quick start guide will cover how to create and send a document package (transaction in the new UI) with the OneSpan Sign REST API. If you do not have a Sandbox account, see the Web UI guide for how you can get signed up.

The REST API

Below is the REST API for creating and sending a package. We used a basically minimum payload as an example where 2 signers, 1 document and 1 signature per signer are added to the package.
For a complete description of each field and other optional attributes, take a look at the JSON Properties section at the end of the guide.
You can find a complete description of each field and all optional attributes in JSON Properties section at the end of the guide. And also refer to the JSON Schema Document for more information.

HTTP Request
POST /api/packages

HTTP Headers
Authorization: Basic api_key
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":"signer1@mailinator.com",
               "firstName":"1.firstname",
               "lastName":"1.lastname",
               "company":"OneSpan Sign"
            }
         ]
      },
      {
         "id":"Role2",
         "signers":[
            {
               "email":"signer2@mailinator.com",
               "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="
}

Configuration

Before you can get started, you will need to set up your environment. This example uses Java and Eclipse. Go ahead and create a new project (e.g. “CreateAndSendPackageRest”) and .java file (e.g. “CreateAndSendPackageRest.java”). If you need help getting this set up, see this previous guide for more detailed instructions on setting up a project.

The Code

This segment of the guide is broken down section by section. You can download the full sample code from the Developer Community Code Share, here.

In the first couple lines, the connection info for your OneSpan Sign connection is defined. If you’re using the production environment, use the url https://apps.esignlive.com/api. Make sure you replace the placeholder text with your API_KEY. You can find this value in the ACCOUNT page when signed into your OneSpan Sign Sandbox account. If you are using the production instance, you will have to contact support to get this key.

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

After that, you will see several other variables being set that we will use 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. This is to give a good representation of the structure of the JSON you will need in order to create your package properly. Many properties are left empty in the string that are not necessary for 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”.

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. 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("Content-Transfer-Encoding: application/pdf").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, creating 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());

}

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.

Capture

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s) 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 patty.galant@mailinator.com
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/…
signature
textual string No No null
handdrawn string Yes No n/a AQAAAMkGIVM7tmRJzS2cANoDcyT0ASABAwA= Signature Import Tool
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 Signing Ceremony 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 bobsmith@email.com(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