OneSpan Sign Developer: Override Account Sender’s Signature

In the previous blog “Upload Signature for Your Signer”, we explored how the captured signature works in OneSpan Sign and how to upload a signature for your signers if your application is integrated and using a custom signature from a signature pad. Today, we will go deeper and discuss two exception scenarios you may encounter when uploading a signature to senders with whom you don’t have access, and you can’t modify their sender profile signature.

Override Account Sender’s Signature

When creating a package with the signer’s signature uploaded, you would add a hand-drawn value into the “signature” block in your request payload directly. However, this practice only works for the signers whose email hasn’t been registered as an account in OneSpan Sign. If you do the same thing with an account sender, OneSpan Sign would recognize the sender and ignore your uploaded signature. To achieve an override of a Sender’s registered signature, you will need to do a couple extra steps. This blog will show you the details of that process.

1. Create your package and leave the status as “DRAFT”.

2. Update your Signer’s signature

First, call the API “GET /api/packages/{packageID}/roles/{roleID}” to grab the whole role’s JSON. 

Then, replace the hand-drawn value with the new signature.

Next, call “PUT /api/packages/{packageID}/roles/{roleID}” to allow the change to take effect.

3. Send your package.
The first time you create a signer, OneSpan Sign will recognize the sender and inject the related role info automatically. This role information includes the hand-drawn signature. With that signature already attached to the signer, OneSpan Sign ignores your uploaded signature and defaults to the signature it already has on file. Through this three steps mentioned above, you update the signer manually and OneSpan Sign won’t match the signer again. Therefore, the modify is valid.

Note:

• This process won’t actually modify the original signature and only work this one time. 
• It can override any account’s signature, including your own account.

Upload Signature for a Notary

While the process above will work in most situations, there are special steps you must take to upload a signature when a notary exists. 

Step1

Create a notarized package without assigning the notaryRoleID and leave it in “DRAFT” status. With the API, replace the notary role information with your own: 

POST /api/packages
Authorization: Basic apikey
Accept: application/json
Content-type: multipart/form-data
Request payload:
{
   "roles":[
      {
         "id":"role1",
         "type":"SIGNER",
         "index":0,
         "signers":[
            {
               "email":"your notary email",
               "firstName":"notary.firstname",
               "lastName":"notary.lastname"
            }
         ],
         "name":"Signer1"
      },
      {
         "id":"role2",
         "type":"SIGNER",
         "index":0,
         "signers":[
            {
               "id":"role2",
               "email":"[email protected]",
               "firstName":"1.firstname",
               "lastName":"1.lastname"
            }
         ],
         "name":"Signer2"
      }
   ],
   "status":"DRAFT",
   "documents":[
      ......
   ],
   "notarized":true,
   "notaryRoleId":null,
   "type":"PACKAGE",
   "name":"test upload signature for notary"
}

Step2

Update signature for notary:
(1). Use GET /api/packages/{packageID}/roles/{notaryRoleID} and copy the whole response body
(2). Update notary:

PUT /api/packages/{packageID}/roles/{notaryRoleID}
Authorization: Basic apikey
Accept: application/json
Content-type: application/json
Request payload:
{
   ...
    "signers": [
        {
          ...
            "signature": {
                "textual": null,
                "handdrawn": "your handdrawn value"
              },
          ...
        }
],
”name”:” Signer1”
}

You will paste the response body in your payload and replace the hand-drawn value with your own.

Step3

Assign notaryRoleID in the package level:

PUT /api/packages/{packageID}
Authorization: Basic apikey
Accept: application/json
Content-type: application/json
Request payload:
{
    "notaryRoleId": "your notary id"
}

Step4

Send the package:

PUT /api/packages/{packageID}
Authorization: Basic apikey
Accept: application/json
Content-type: application/json
Request payload:
{
    "status": "SENT"
}

Note:

• Step 3 and step 4 must be done through two separate API calls.

The main point behind these four steps is, if you follow the process we did in the first section, you will receive an error that says "you can’t edit a notary". But, if you don't assign a notary until updating his/her hand-drawn value, you are able to avoid this error, and everything works as expected. 

If you have access to your senders and notaries, it’s still better to update your sender profile signature, and it’s always recommended to test the whole process in Postman before you implement it in code. 

If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!