2. Check Package Status and Download Documents

Following up on the creating and sending a document package quick start guide, this guide will cover some things you can do after sending the package, such as: checking the package/signing status, downloading the e-signed documents, and downloading the evidence summary.

This guide will follow up on the Creating and Sending a Package with REST API guide. If you followed along, you had just looked in your OneSpan Sign inbox to see that your document package (transaction in the new UI) was created and sent properly after executing the REST call built in the guide.

Capture

The REST API

In this guidance, four API functions will be involved. In first call, we will first retrieve the whole package JSON, and obtain the package status. Second call, we’ll grab the Signing Status for the whole package or specific signer of specific document. Finally, we will call REST API to download the documents zip and evidence summary if the package is completed.

1. Retrieve Package JSON

HTTP Request
GET /api/packages

HTTP Headers
Accept: application/json
Authorization: Basic api_key

For a complete description for each field in response, you can refer to last guidance.

2. Retrieving Signing Status

HTTP Request
GET /api/packages/{packageId}/signingStatus?signer={signerId}&document={documentId}

HTTP Headers
Accept: application/json
Authorization: Basic api_key

Response Payload

{
    "status": "COMPLETED"
}

Note:
1. “signerId” in this API call can be replaced by signer’s email.
2. The possible status are: ARCHIVED/ CANCELED/ COMPLETE/ DECLINED/ EXPIRED/ INACTIVE/ OPTED_OUT/ COMPLETED/ SIGNING_PENDING.

3. Download Documents Zip

HTTP Request
GET /api/packages/{packageId}/documents/zip

HTTP Headers
Accept: application/zip
Authorization: Basic api_key

4. Download Evidence Summary

HTTP Request
GET /api/packages/{packageId}/evidence/summary

HTTP Headers
Accept: application/pdf
Authorization: Basic api_key

Configuration

Initial Setup

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. “CheckStatusAndDownloadREST”) and a .cs file (e.g. “CheckStatusAndDownloadREST.cs”). If you need help getting this set up, head over to the Creating and Sending a Package with 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.

Locating the Package ID of your Existing Project

Since the package you are working with was created previously, we need to find the package ID for use in this project. If you select the project from the UI inbox, as seen above, the URL will have the package ID, like this:

https://sandbox.esignlive.com/a/transaction/IW30CWirli6h6gZQqqfFXdrPSqA=

In the C# class you created in the last guide, you will see that the package ID was returned in the HTTP response you received from your REST call.

Capture

If you were creating a more complex application, you would likely store this package ID for use within other parts of your application, versus looking it up in your OneSpan Sign URLs.

The Code

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

The first couple lines are where the connection info for your OneSpan Sign connection is defined. If you are 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";

Next, you will create the HttpClient that you will use to make your GET requests 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,application/zip,text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8");

Check the Status

For this section, you will need the packageId that you found above. With that handy, you can set up your GET request to see what the package status is. The possible values are ARCHIVED, COMPLETED, DECLINED, DRAFT, EXPIRED, OPTED_OUT, and SENT. The code below performs a GET request to the url created from the base url defined above with the remainder of the url from the appropriate REST call defined in the documentation (in this case, “/packages/YOUR_PACKAGE_ID”). The content of the response is then parsed into a JObject and the “status” property of the JObject is obtained and written to the Debug output.

var packageStatusResponse = myClient.GetAsync(new Uri(url + "/packages/YOUR_PACKAGE_ID")).Result;
JObject packageStatusResponseJSON = JObject.Parse(packageStatusResponse.Content.ReadAsStringAsync().Result);
var packageStatus = packageStatusResponseJSON["status"];
Debug.WriteLine("Package Status: " + packageStatus);

Next, check the signing status of the package. The possible values for this one are ARCHIVED, CANCELED, COMPLETE, DECLINED, EXPIRED, INACTIVE, OPTED_OUT, COMPLETED, and SIGNING_PENDING. This is done exactly the same as the last step except for an addition of “/signingStatus” to the request url. Write the response for this call to the Debug output window, as well.

var signingStatusResponse = myClient.GetAsync(new Uri(url + "/packages/0487df67-6417-48f8-9575-b520c0f977ff/signingStatus")).Result;
JObject signingStatusResponseJSON = JObject.Parse(signingStatusResponse.Content.ReadAsStringAsync().Result);
var signingStatus = signingStatusResponseJSON["status"].ToString();
Debug.WriteLine("Signing Status: " + signingStatus);

Download the Files

For the last part, you will check to see if the package is complete. If it is, the zip file of all documents will be downloaded, as well as the evidence summary. After each step, write to the Debug output so that you know the event happened when you test the class in the next step. Also, note the additions to the base url for each download.

if (signingStatus.Equals("COMPLETED"))
{
   var downloadZipResponse = myClient.GetAsync(new Uri(url + "/packages/0487df67-6417-48f8-9575-b520c0f977ff/documents/zip")).Result;
   ByteArrayContent content = new ByteArrayContent(downloadZipResponse.Content.ReadAsByteArrayAsync().Result);
   File.WriteAllBytes("C:/Eclipse/myzip.zip", content.ReadAsByteArrayAsync().Result);
   Debug.WriteLine("Zip File Downloaded");
 
   var evidenceSummaryResponse = myClient.GetAsync(new Uri(url + "/packages/0487df67-6417-48f8-9575-b520c0f977ff/evidence/summary")).Result;
   ByteArrayContent evidenceSummaryContent = new ByteArrayContent(evidenceSummaryResponse.Content.ReadAsByteArrayAsync().Result);
   File.WriteAllBytes("C:/Eclipse/myevidencesummary.pdf", evidenceSummaryContent.ReadAsByteArrayAsync().Result);
   Debug.WriteLine("Evidence Summary Downloaded");
}
else
{
   Debug.WriteLine("Signing not complete");
}

Running the Code

Execute your C# class by clicking the Start button from the toolbar.

If you have not yet signed your package, your Output should look like the following:

Capture

After signing your package, you will get the following in your Output window:

Capture

If you now browse to the location where you saved your files, you will see that your files were successfully downloaded.

Capture

Get the Code

This guide will follow up on the Creating and Sending a Package with REST API guide. If you followed along, you had just looked in your OneSpan Sign inbox to see that your document package (transaction in the new UI) was created and sent properly after executing the REST call built in the guide.

Capture

The REST API

In this guidance, four API functions will be involved. In first call, we will first retrieve the whole package JSON, and obtain the package status. Second call, we’ll grab the Signing Status for the whole package or specific signer of specific document. Finally, we will call REST API to download the documents zip and evidence summary if the package is completed.

1. Retrieve Package JSON

HTTP Request
GET /api/packages

HTTP Headers
Accept: application/json
Authorization: Basic api_key

For a complete description for each field in response, you can refer to last guidance.

2. Retrieving Signing Status

HTTP Request
GET /api/packages/{packageId}/signingStatus?signer={signerId}&document={documentId}

HTTP Headers
Accept: application/json
Authorization: Basic api_key

Response Payload

{
    "status": "COMPLETED"
}

Note:
1. “signerId” in this API call can be replaced by signer’s email.
2. The possible status are: ARCHIVED/ CANCELED/ COMPLETE/ DECLINED/ EXPIRED/ INACTIVE/ OPTED_OUT/ COMPLETED/ SIGNING_PENDING.

3. Download Documents Zip

HTTP Request
GET /api/packages/{packageId}/documents/zip

HTTP Headers
Accept: application/zip
Authorization: Basic api_key

4. Download Evidence Summary

HTTP Request
GET /api/packages/{packageId}/evidence/summary

HTTP Headers
Accept: application/pdf
Authorization: Basic api_key

Configuration

Initial Setup

Go ahead and create a new .java file for this tutorial. You can either start a new project or simply create a new class in a previously created project. For example, “CheckStatusAndDownloadRest.java”. Working with REST API requires the use of JSON. In order to work with it more easily, an external library org.json is used. The jar file can be found here. If you require help on how to import external libraries, follow the steps in this previous guide.

Locating the Package ID of your Existing Project

For this example, you will need a packageId from a previously created document package. The two most likely methods to retrieve your packageId are to navigate to the package in the UI and retrieve it from the URL, or similarly in the previous guide, the packageId was returned in the HTTP response you received from you REST call.

The Code

This segment of the guide only shows snippets of code. You can download the full sample code from the Code Share.

The first two lines is where your connection info for your e-SignLive connection is defined. If you are on the production environment, change the url to https://apps.e-signlive.com/api. Make sure to replace the placeholder text with your API_KEY. In the Sandbox, your API_KEY can be found in the ACCOUNT page when you sign into your OneSpan Sign account. If in production, you will need to get this from support.

String API_KEY = "YOUR_API_KEY";
String url = "https://sandbox.e-signlive.com/api/packages";

The next couple of lines is where you create your connection to make your GET request and set the appropriate header content-type, authorization, and accept values.

URL client = new URL(url + "/1edd9f11-9bcc-4587-94e8-aa6478bbda4d/");
HttpURLConnection conn = (HttpURLConnection) client.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Authorization", "Basic " + API_KEY);
conn.setRequestProperty("Accept", "application/json");

Check the Status

In this section, you will need your package id that you have found previously. With it, you are ready to make your GET request to determine the status of your package. The two lines below is where we get the status code from the HTTP response message. If the request is successful, responseCode should print out 200.

int responseCode = ((HttpURLConnection) conn).getResponseCode();

If the request is successful, you create an input stream and read from the connection in a BufferedReader. The JSON content of the response is subsequently parsed into a JSONObject and printed out. The status of the package is given in the “status” property of the JSONObject.

System.out.println(responseCode + " OK!");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
 
while ((inputLine = in.readLine()) != null) {
   response.append(inputLine);
}
 
in.close();
 
JSONObject json = new JSONObject(response.toString());
System.out.println(json.getString("status"));

Retrieving the signing status of your package is done exactly the same way except for an addition of “/signingStatus” to the request url.

URL client2 = new URL(url + "/1edd9f11-9bcc-4587-94e8-aa6478bbda4d/signingStatus");
HttpURLConnection conn2 = (HttpURLConnection) client2.openConnection();
conn2.setRequestProperty("Content-Type", "application/json");
conn2.setRequestProperty("Authorization", "Basic " + API_KEY);
conn2.setRequestProperty("Accept", "application/json");
 
int responseCode2 = ((HttpURLConnection) conn2).getResponseCode();
         
if (responseCode2 == 200) {
   System.out.println(responseCode2 + " OK!");
     
   BufferedReader in2 = new BufferedReader(new InputStreamReader(conn2.getInputStream()));
   String inputLine2;
   StringBuffer response2 = new StringBuffer();
     
   while ((inputLine2 = in2.readLine()) != null) {
      response2.append(inputLine2);
   }
     
   in2.close();
   conn2.disconnect();
             
   JSONObject json2 = new JSONObject(response2.toString());
   System.out.println(json2.getString("status"));

Download the Files

This segment covers how to download your package into a zip file on your desktop, as well as the evidence summary. The first couple of lines remain the same. As a reminder, make sure to add “/documents/zip” the request url.

if (json2.getString("status").equals("COMPLETED")){
  
   URL client3 = new URL(url + "/1edd9f11-9bcc-4587-94e8-aa6478bbda4d/documents/zip");
   HttpURLConnection conn3 = (HttpURLConnection) client3.openConnection();
   conn3.setRequestProperty("Content-Type", "application/json");
   conn3.setRequestProperty("Authorization", "Basic " + API_KEY);
   conn3.setRequestProperty("Accept", "application/zip");
 
   int responseCode3 = ((HttpURLConnection) conn3).getResponseCode();
   System.out.println(responseCode3 + " OK!");
   System.out.println("Downloading zip files....");

We then open the input stream from the HTTP connection. You can specify any location you wish on your computer. Do not forget to replace the placeholder text with your account name.

InputStream inputStream = conn3.getInputStream();
String saveFilePath = "C:/Users/your_account/Desktop/yourFiles.zip";

Next, open an output stream to write the zip file in the specified location. After all the data is written, go ahead and close the connection.

FileOutputStream outputStream = new FileOutputStream(saveFilePath);
 
int bytesRead = -1;
byte[] buffer = new byte[4096];
while ((bytesRead = inputStream.read(buffer)) != -1) {
   outputStream.write(buffer, 0, bytesRead);
}
 
System.out.println("Zip files downloaded!");
outputStream.close();
inputStream.close();
conn3.disconnect();

To download the evidence summary, the code is almost identical to downloading the zip file, with the exception of the “Accept” header field. Make sure to change that to “application/pdf”.

URL client4 = new URL(url + "/1edd9f11-9bcc-4587-94e8-aa6478bbda4d/evidence/summary");
HttpURLConnection conn4 = (HttpURLConnection) client4.openConnection();
conn4.setRequestProperty("Content-Type", "application/json");
conn4.setRequestProperty("Authorization", "Basic " + API_KEY);
conn4.setRequestProperty("Accept", "application/pdf");
     
int responseCode4 = ((HttpURLConnection) conn4).getResponseCode();
System.out.println(responseCode4 + " OK!");
System.out.println("Downloading evidence summary....");
                 
inputStream = conn4.getInputStream();
saveFilePath = "C:/Users/your_account/Desktop/evidenceSummary.pdf";
     
outputStream = new FileOutputStream(saveFilePath);
     
bytesRead = -1;
buffer = new byte[4096];
while ((bytesRead = inputStream.read(buffer)) != -1) {
   outputStream.write(buffer, 0, bytesRead);
}
                 
System.out.println("Evidence summary downloaded!");
outputStream.close();
inputStream.close();
conn4.disconnect();

Running the code

Press the run button in your IDE. If the package was already signed, the output should look like the following:

Capture

If you browse to the location you specified to save your zip file and evidence summary, you will find your files (if your package was completed):

Capture

Get the Code