OneSpan Sign Developer: Retrieve Sender Packages
In this blog, I will walk you through what you might have missed in the OneSpan Sign Developer Community during the week of July 22nd, 2018. Today, we are covering the differences between account owners and senders. Without further ado, let's get started.
Account Owner vs Sender
As an account owner, OneSpan Sign provides you with the ability to add senders to your main account, allowing them to create and send document packages.
There are a few differences between an account owner and sender:
- As an account owner, in the Web UI, when you click on the pulldown list next to your name on the top of the screen, you will see your role as “Manager”. Common senders, however, will be defaulted to the role of “Member”.
- Only an account owner has the “Admin” option in this pulldown list. However, what we will discuss in this blog is that only an account owner can retrieve an API Key. Senders cannot directly obtain keys through the Web UI. This means that senders cannot send an API call or call SDK functions themselves.
How to Retrieve the Sender Packages and Information
As an account owner, you must be wondering how to manage packages, templates, and layouts for senders, since they cannot retrieve their information programmatically. Below is a step-by-step guide to manage these elements.
1. Retrieve the Sender’s API Key
To retrieve this information, you need to get your sender’s API key, and use this token to call APIs just like what you did with your main owner account. There are two steps to achieve this:
First, you’d retrieve the sender ID(s) in one of two ways. The following will grab the first 50 senders from your account, which you could loop through to access the sender IDs:
GET https://sandbox.esignlive.com/api/account/senders?from=0&to=50.
If you’re only interested in a single Sender, you can do a direct search for that sender with the following call:
GET https://sandbox.esignlive.com/api/account/senders?search={signerEmail}
Then, once you have the sender ID, you can use the API below to retrieve the API key of the current sender. Even though we mention that senders cannot see their API keys themselves, OneSpan Sign does have an assigned key to each sender, and as an account owner, you are allowed to retrieve them by:
GET https://sandbox.esignlive.com/api/account/senders/{senderId}/apiKey
Kindly note that, this function is currently only available through REST API.
2. Retrieve List of Layouts
GET /api/layouts?from={fromLayout}&to={toLayout}
Authorization: Basic {your sender’s api key}
3. Retrieve List of Package IDs
You can use the following API call to directly retrieve packages for a specific sender. Remember, this API call only returns packages created under the main account owner if you are using an owner’s API key. So instead, you should put sender’s key in the request header.
GET /api/packages?query={status}&from={fromPackage}&to={toPackage}
Authorization: Basic {your sender’s api key}
Alternatively, you can simply use the Completion Report Feature to retrieve all senders’ package IDs. Using this strategy, you don’t necessarily need to get the sender’s API key.
GET /api/reports/completion?status={status}&from={fromDate}&to={toDate}
Authorization: Basic {account owner’s key}
Keywords Search
OneSpan Sign gives you the capability to filter retrieved results by keywords. You can simply add a “&search={keyword}” parameter to your API call for the following three scenarios:
For Retrieve Packages:
GET /api/packages?search={keyword}&from={fromPackage}&to={toPackage}
For Retrieve Templates:
GET /api/packages?type=TEMPLATE&search={keyword}&from={fromTemplate}&to={toTemplate}
For Retrieve Layouts:
GET /api/layouts?search={keyword}&from={fromLayout}&to={toLayout}
Notice:
1. Template is a kind of package with type of “template”
2. In a URL, the value of keyword and type (which is template here) parameters are not case sensitive. Unlike status parameter, which indicates the package status. For example, “DRAFT” or “SENT” must be written in all capital letters.
3. “From” and “to” in the above searches are integers corresponding to the package/template/layout’s order in the list of elements.
You can alternatively use SDK functions together with related parameters to achieve the same goal other than the one to retrieve the senders’ API keys.
If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums.
