Get Started

OneSpan Blog

OneSpan Sign Developer: Multiple Signers Sharing the Same Email

E-Signature Developers
Duo Liang,
OneSpan Sign Developer: Multiple Signers Sharing the Same Email

Can multiple recipients share the same email address in OneSpan Sign? 

We hear this question a lot when spouses or applicant and co-applicant share a single email address. In this blog, we will explain how OneSpan Sign facilitates these use cases and showcase sample workflows for both ad-hoc and integrated users. Without further delay, let’s get started!

Native Support in UI

Mr. and Mrs. Smith are ready to e-sign a car loan contract, and because it’s a family affair, they prefer to use a shared family email as their individual email address and to receive any subsequent email notifications regarding this transaction. 

Their agent has logged onto the OneSpan Sign sender portal and is preparing the transaction for the Smith family. Since the feature is natively supported by OneSpan Sign, it’s very straightforward to achieve the goal by simply entering the same email address for both recipients.

10-21-1

As long as the first and last names differ, they will be identified as individual signers, and the sender can assign separate signatures for them. 

10-21-2

Note that this feature is only available for external recipients who do not have a OneSpan Sign account. If you added two signers sharing the sender’s email address, you could still receive the error message below:

10-21-3

In order to maximize the traceability and to ensure the probative value of the contract, OneSpan Sign strongly recommends that senders enforce an authentication method. Here we will follow this advice and assign a Q&A authentication for both recipients to better identify themselves before accessing the signing ceremony.

10-21-4

When the transaction is sent out, the shared email address will receive multiple email notifications for each recipient with different signing links.

10-21-5

Best Practice for Integrated Users

Similar to ad-hoc users, integrators can also implement this workflow via SDK and REST APIs. In this section, we will walk through the necessary steps and highlight the differences compared to the typical package creation.

Create a Package

To programmatically create a package where multiple recipients share the same email address, API users could simply specify the same email address for the recipients without modifying the remaining JSON payload.

However this becomes trickier for SDK users. Below is a working example in Java SDK:

DocumentPackage pkg = PackageBuilder.newPackageNamed("Sample Package with Multiple Recipients Sharing the Same Email")
            .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
                .withCustomId("Signer1")
                .withFirstName("John")
                .withLastName("Smith"))
            .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
	        .withCustomId("Signer2")
	        .withFirstName("Mary")
	        .withLastName("Smith"))
            .withDocument(DocumentBuilder.newDocumentWithName("Document1")
                .fromFile("file_path_to_the_document")
                .withId("Document1")
                .withSignature(SignatureBuilder.signatureFor(new Placeholder("Signer1"))
                    .onPage(0)
                    .atPosition(100, 100)
                    .withSize(200, 55)
                )
                .withSignature(SignatureBuilder.signatureFor(new Placeholder("Signer2"))
	           .onPage(0)
                    .atPosition(100, 300)
                    .withSize(200, 55)
                )
            )
            .withStatus(PackageStatus.SENT)
            .build();
PackageId packageId = eslClient.createPackageOneStep(pkg);

There are two noticeable changes we’ve made compared to the basic package creation. First in the add-signer section, we invited two signers with the same email address, and specifying unique custom IDs is a MUST in this scenario:

.withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
                .withCustomId("Signer1")
                .withFirstName("John")
                .withLastName("Smith"))
            .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
	       .withCustomId("Signer2")
	       .withFirstName("Mary")
	       .withLastName("Smith"))

Second when assigning signatures, instead of referring to the signer email, we need to bind the signature to the custom ID.

.withSignature(SignatureBuilder.signatureFor(("[email protected]"))	         //normal package creation
.withSignature(SignatureBuilder.signatureFor(new Placeholder("Signer1"))	         //refer to custom ID

Build Signing Links 

If you are embedding the signing process and presenting the Signing Ceremony within your application, the next step is to generate either a Signing URL or a link built by the signer authentication token.

For the former, the process generating a signing URL is exactly the same as your normal flow. It can be achieved with either this API:

GET /api/packages/{packageId}/roles/{roleId}/signingUrl

Or with this SDK function:

String signingUrl = eslClient.getPackageService().getSigningUrl(packageId, customId);

However if you are building a signer authentication token, it doesn’t fit the use cases when the same email is shared by multiple signers. Therefore you need to make sure your code is ONLY using the signer ID in these APIs:

HTTP Request

POST /api/authenticationTokens/signer/multiUse

Or

POST /api/authenticationTokens/signer/singleUse

Request Payload

{
    "packageId": "5vjLRY5MWrDJ6MzRAEyCKOy5IH0=",
    "signerId": "Signer1"
}

Or use custom ID in these SDK functions:

String signerAuthToken = eslClient.getAuthenticationTokensService().createSignerAuthenticationToken(packageId, customId);
String singleUseToken = eslClient.getAuthenticationTokensService().createSignerAuthenticationTokenForSingleUse(packageId, customId);

Check Signing Status

The same code changes could be required when you are actively polling signing status through the API where your code should ONLY use signer ID to identify a signer:

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

Or this SDK function:

SigningStatus signerStatus = eslClient.getSigningStatus(packageId, new SignerId(customId), null);

Visit the Developer Community Forums

In this blog, we reviewed how the OneSpan Sign UI portal supports the use-case when husband and wife share the same email address and the technical details to reproduce the same through SDK and API codes.

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!

OneSpan Developer Community

OneSpan Developer Community

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

Join Today
Duo Liang
Duo Liang

Duo Liang is a Technical Evangelist and Partner Integrations Developer at OneSpan where he creates and maintains integration guides and code shares, helps customers and partners integrate OneSpan products into their applications, and builds integrations within third party platforms.

Go To Top
Share