OneSpan Sign How To: Create and Send A Package with REST in Perl

Perl is a general purpose programming language that was originally intended for text manipulation. These days, however, it used in a wide variety of applications, such as web development. Over the years, it gained popularity amongst developers due to its flexibility, portability, usefulness, and its varied features. It is also one of the most popular programming languages when it comes to CGI (Common Gateway Interface) programming on the Web. In this blog, I will show you how to create and send a package with the REST API in Perl.

The Code

For my example, I will be using Perl Strawberry 5.24 for Windows. If you don’t already have it installed, you can download it from the official website, here. The complete example code is available on our Developer Community Code Share.

Let's get started. In your favorite text editor, create a new file name "CreateAndSendPackage.pl" and save it in a location of your choice. You can go ahead and copy the code below. I will go over it in more detail further down.

use LWP::UserAgent;
use File::Slurp;
use warnings;
use strict;

my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->default_header('Accept-Encoding' => scalar HTTP::Message::decodable());
$ua->add_handler("request_send",  sub { shift->dump; return });

my $url = "https://sandbox.esignlive.com/api/packages";

my $json = '{"documents":[{"approvals":[{"id":"ExampleSignatureId","role":"Signer1","fields":[{"page":0,"top":507,"subtype":"LABEL","height":60,"left":573,"width":122,"id":"dateField","type":"INPUT","binding":"{approval.signed}"},{"id":"signatureField","page":0,"top":507,"subtype":"FULLNAME","height":60,"left":213,"width":312,"type":"SIGNATURE"}],"name":""}],"id":"sample-contract","name":"Test Document"}],"status":"SENT","type":"PACKAGE","roles":[{"id":"Signer1","type":"SIGNER","signers":[{"email":"[email protected]","firstName":"John","lastName":"Smith","id":"Signer1"}],"name":"Signer1"}],"name":"Create and Send Package in Perl"}';

my $pdf = "sample_contract.pdf";
my $field_name_1 = "file";
my $field_name_2 = "payload";

my $response = $ua->post( $url,
			Authorization => 'Basic your_api_key',
			Accept => 'application/json',
			Content_Type => 'form-data',
			Content => [ $field_name_1 => ["$pdf"] , $field_name_2 => $json]
			);

print $response->content;

Now, let’s go over the code in greater detail. The first couple of lines imports the modules needed in order to make HTTP requests to OneSpan Sign's API.

use LWP::UserAgent;
use File::Slurp;
use warnings;
use strict;

These modules come pre-installed with Perl Strawberry. Next, we will need to create our User Agent object. Namely, this object implements a web user agent capable of making HTTP/S requests. I also configured the User Agent such that it times out after 10 seconds and prints out the request to the console for debugging purposes.

my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->default_header('Accept-Encoding' => scalar HTTP::Message::decodable());
$ua->add_handler("request_send",  sub { shift->dump; return });

The next line is the endpoint url where you will make your POST request to.

my $url = "https://sandbox.esignlive.com/api/packages";

Then, the JSON string that defines your package is created. You would typically build your JSON string dynamically versus having a big string like in this example. I chose to do so for simplicity.

my $json = '{"documents":[{"approvals":[{"id":"ExampleSignatureId","role":"Signer1","fields":[{"page":0,"top":507,"subtype":"LABEL","height":60,"left":573,"width":122,"id":"dateField","type":"INPUT","binding":"{approval.signed}"},{"id":"signatureField","page":0,"top":507,"subtype":"FULLNAME","height":60,"left":213,"width":312,"type":"SIGNATURE"}],"name":""}],"id":"sample-contract","name":"Test Document"}],"status":"SENT","type":"PACKAGE","roles":[{"id":"Signer1","type":"SIGNER","signers":[{"email":"[email protected]","firstName":"John","lastName":"Smith","id":"Signer1"}],"name":"Signer1"}],"name":"Create and Send Package in Perl"}';

Next, a few variables are created in order to make our POST request. Note that in my example, my PDF document is in the same directory as my Perl script. If your PDF document is located somewhere else, you will need to put the complete path to the document as opposed to simply declaring its name.

my $pdf = "sample_contract.pdf";
my $field_name_1 = "file";
my $field_name_2 = "payload";

Finally, we set the required headers and make our HTTP POST request. The response will subsequently be printed to the console.

my $response = $ua->post( $url,
			Authorization => 'Basic your_api_key',
			Accept => 'application/json',
			Content_Type => 'form-data',
			Content => [ $field_name_1 => ["$pdf"] , $field_name_2 => $json]
			);

print $response->content;

Running Your Code

Open your command prompt and change the current directory to the location where you saved your "CreateAndSendPackage.pl" file. Then, enter the following line:

perl CreateAndSendPackage.pl

OneSpan Sign will then return a package id as a response, which will be printed to the command prompt window.

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://developer.onespan.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter 

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today