OneSpan Sign Developer: Role vs Signer - Part 2
Last week, we explored the JSON structure of Role and Signer, the detailed meaning of these two concepts, as well as the methods to retrieve IDs for them in REST way. In this blog, I will guide you through the scenarios and API calls where you will need to use the Role ID along with the Signer ID.
To begin, let’s briefly recap Role and Signer:
- Signer contains user’s personal information, and it is included in Role.
- Role acts as a placeholder and is bound to the Approval(s) that are made up of a Signer’s Signatures and Fields.
If you are still confused or you missed something, you can kindly check my last week’s blog, “OneSpan Sign Developer: Role vs Signer” or post a question in our Developer Forum.
Where to Use Signer ID
Remember, Signer is related to the specific person. Email address is the only thing to uniquely identify a signer, and Signer ID can be replaced by email. Here are two scenarios where you use Signer ID in which it sticks to the email of signer:
To Retrieve Signing Status:
OneSpan Sign provides you with different searching grains for Signing Status, which means you can check the status for the whole package or just for a signer within a specific document. You can optionally choose signer and document parameters in below API URL to achieve this:
GET /api/packages/{packageId}/signingStatus?signer={signerId}&document={documentId}
Check out this forum post for further details.
To Retrieve Authentication Token:
An authentication token is used to obtain a valid session for a signer or to generate the signing URL.
There are three API calls to retrieve authToken for a signer:
POST /api/authenticationTokens/signer/singleUse
POST /api/authenticationTokens/signer/multiUse
POST /api/signerAuthenticationTokens
The first API call is to generate a single use of authentication token. While the last two APIs both generate multiple use of authToken so that you can consider them as interchangeable, all of them come with same request payload:
{
"packageId": "your package id",
"signerId": "signer ID or signer email"
}
Notice:
- You can only generate an authentication token for your signer with package in a “SENT” status. Otherwise, you would receive a “400 error” explaining that this package is in an invalid state.
- Signer’s email also works in the request payload.
- All authentication tokens will expire in 30 minutes.
- Both sessionToken (generated by authToken) and authenticationToken can be used to generate signing URL for a signer by replacing the placeholder in this URL: https://sandbox.esignlive.com/access?sessionToken={signerAuthToken}
Where to Use Role ID
Role ID has a wider usage than Signer ID. In our API Specification Site, you can find detailed examples of services where Role ID is used:
- To manage a role
- To reorder a role
- To unlock a signer
- To send an Email invitation for signing
- To send an SMS authentication passcode to a signer
In addition, you can also use Role ID in the following scenarios:
To Generate the Signing URL for a Signer
Other than using Signer ID to generate a signing URL, you can also follow below API. The generated URL is different than the one above and can be used multiple times. This URL is like the one the Signer would receive in their email. You probably would not want to embed this URL into the src of an iframe as it doesn’t expire.
GET /api/packages/{packageId}/roles/{roleId}/signingUrl
To Extract the Signature Image for a Signer
Once your signer captured their signature, you can download the signature image and store it in your own system for further use. The default downloaded image size is 350 x 100 pixels, and this feature is only available for version 11 of OneSpan Sign.
HTTP Request
GET /api/packages/{packageId}/roles/{roleId}/signatureImage
HTTP Headers
Accept: image/png,image/jpeg,image/gif
Content-Type: application/json
Authorization: Basic api_key
If you have any questions regarding this blog or anything else about integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!
