OneSpan Sign How To: Managing Senders
OneSpan Sign provides you with the ability to add senders to your account, allowing them to create and send document packages for signature. As an account owner, you will have access to the packages created by your senders. Though, you'll only be able to retrieve the packages created by your senders through the SDKs/API. If you want to access from the UI the packages created by your senders, you will need your senders to delegate access to you. This is also the case for the reverse situation. For more information on delegating access, see this previous blog.
There are three types of senders: Owner, Admin, and basic Senders. The Owner is the account holder and cannot be changed. An Admin can invite users to be senders in the account and appoint senders as admins. All account types can create and send packages. It is also important to note that a sender can only be member of one account. In this blog, I will show you how to manage your senders with the OneSpan Sign Java SDK, .NET SDK, and REST API.
Senders in the UI
Before getting into the code, you should locate your senders section in your UI. After logging into your OneSpan Sign account, click on ACCOUNT in your toolbar and then on the Senders tab. After running your code, you should find your senders here. 
The Code
Now that our objective is set, let’s get started with the code. I will cover the exact same information for each method. Feel free to skip to the section which applies to you. Full code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST. Java SDK I’ll start with the Java SDK. To invite a user to be a sender in your account, you will need to build an AccountMember object. Then, you call on your OneSpan Sign AccountService to send the invitation. When a new sender is invited to join an account, they are by default added in an inactive state. The sender will receive an email containing a link that they will need to click to activate their account. You can skip the verification step by setting the status to ACTIVE when building your AccountMember object, if your sender already has an OneSpan Sign account.
AccountMember member = AccountMemberBuilder.newAccountMember("[email protected] ")
.withFirstName("John")
.withLastName("Smith")
.withCompany("ABC Bank")
.withTitle("CEO")
.withStatus(SenderStatus.ACTIVE)
.build();
client.getAccountService().inviteUser(member);
You can also retrieve your senders by calling on your OneSpan Sign AccountService. Below is a sample code on how to retrieve all your senders, which comes as a page from OneSpan Sign, along with their emails and ids.The sender’s ID is required in order to update or delete a sender. In the code below, the number of senders returned in the PageRequest is set to 5. The maximum number of senders that you can retrieve per page is 50. The first value in the PageRequest (variable ‘i’) is the starting point in the overall list of senders that should be returned. This variable is incremented as we step through our senders to keep track of where we are in the overall list of senders
int i = 1;
Map<String, Sender> accountMembers = client.getAccountService().getSenders(Direction.ASCENDING, new PageRequest(i,5));
while (!accountMembers.isEmpty()) {
for (Map.Entry<String, Sender> entry : accountMembers.entrySet())
{
System.out.println(entry.getKey() + " / " + entry.getValue().getId());
i++;
}
accountMembers = client.getAccountService().getSenders(Direction.ASCENDING, new PageRequest(i,5));
}
As mentioned above, you will need the sender ID to update your sender. Note that the email address cannot be updated once you’ve created your sender. You will need to create a new sender, in this case.
SenderInfo updatedSenderInfo = SenderInfoBuilder.newSenderInfo("[email protected]")
.withName( "John", "Smith" )
.withTitle( "CEO" )
.withCompany("XYZ Bank")
.build();
client.getAccountService().updateSender(updatedSenderInfo, "{senderId}");
Similarly, you will also need the sender ID to delete your sender. If your sender has packages in their inbox or in draft status, the sender will be locked instead of being deleted, and will not be able to create or send packages anymore.
client.getAccountService().deleteSender("{senderId}");
Finally, here is a sample code on how you would build a document package to be sent by a particular sender from your account:
DocumentPackage packageToSend = PackageBuilder.newPackageNamed("Cleaning Contract Example")
.withSenderInfo(SenderInfoBuilder.newSenderInfo("[email protected]"))
.withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
.withFirstName("Mary")
.withLastName("Doe")
.withCustomId("client"))
.withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
.withFirstName("John")
.withLastName("Smith")
.withCustomId("contractor"))
.withDocument(DocumentBuilder.newDocumentWithName("Contract.pdf")
.fromStream(new FileInputStream("DOC_FILE_PATH"), DocumentType.PDF)
.enableExtraction())
.build();
.NET SDK Next, I’ll continue with the .NET SDK. To invite a user to be a sender in your account, you will need to build an AccountMember object. Then, you call on your OneSpan Sign AccountService to send the invitation. When a new sender is invited to join an account, they are by default added in an inactive state. The sender will receive an email containing a link that they will need to click to activate their account. You can skip the verification step by setting the status to ACTIVE when building your AccountMember object, if your sender already has an OneSpan Sign account.
AccountMember member = AccountMemberBuilder.NewAccountMember("[email protected]")
.WithFirstName("John")
.WithLastName("Smith")
.WithCompany("ABC Bank")
.WithTitle("CEO")
.WithStatus(SenderStatus.ACTIVE)
.Build();
client.AccountService.InviteUser(member);
You can also retrieve your senders by calling on your OneSpan Sign AccountService. Below is a sample code on how to retrieve all your senders, which comes as a page from OneSpan Sign, along with their emails and ids. The sender's ID will be required in order to update or delete a sender. In the code below, the number of senders returned in the PageRequest is set to 5. The maximum number of senders that you can retrieve per page is 50. The first value in the PageRequest (variable ‘i’) is the starting point in the overall list of senders that should be returned. This variable is incremented as we step through our senders to keep track of where we are in the overall list of senders
int i = 1;
IDictionary<string, Sender> accountMembers = client.AccountService.GetSenders(Direction.ASCENDING, new PageRequest(i, 5));
while (accountMembers.Count != 0)
{
foreach (KeyValuePair<string, Sender> entry in accountMembers)
{
Debug.WriteLine(entry.Key + " / " + entry.Value.Id);
i++;
}
accountMembers = client.AccountService.GetSenders(Direction.ASCENDING, new PageRequest(i, 5));
}
As mentioned above, you will need the sender ID to update your sender. Note that the email address cannot be updated once you’ve created your sender. You will need to create a new sender in this case.
SenderInfo updatedSenderInfo = SenderInfoBuilder.NewSenderInfo("[email protected]")
.WithName( "John", "Smith" )
.WithTitle( "CEO" )
.WithCompany("XYZ Bank")
.Build();
client.AccountService.UpdateSender(updatedSenderInfo, "{senderId}");
Similarly, you will also need the sender ID to delete your sender. If your sender has packages in their inbox or in draft status, the sender will be locked instead of being deleted, and will not be able to create or send packages anymore.
client.AccountService.DeleteSender("{senderId}");
Finally, here is a sample code on how you would build a document package to be sent by a particular sender from your account:
DocumentPackage packageToSend = PackageBuilder.NewPackageNamed("Cleaning Contract Example")
.WithSenderInfo(SenderInfoBuilder.NewSenderInfo("[email protected]"))
.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected] ")
.WithFirstName("Mary")
.WithLastName("Doe")
.WithCustomId("client"))
.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
.WithFirstName("John")
.WithLastName("Smith")
.WithCustomId("contractor"))
.WithDocument(DocumentBuilder.NewDocumentNamed("Contract.pdf")
.FromStream(new FileStream("DOC_FILE_PATH", FileMode.Open), DocumentType.PDF)
.EnableExtraction())
.Build();
OneSpan Developer Community
Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.
Join TodayREST API
Lastly, I’ll go over the REST API. To invite a user to be a sender in your account, you will need to build the JSON below. Then, you make your POST request to: https://sandbox.onespan.com/api/account/senders. When a new sender is invited to join an account, they are by default added in an inactive state. The sender will receive an email containing a link that they will need to click to activate their account. You can skip the verification step by setting the status to ACTIVE when building your JSON, if your sender already has an OneSpan Sign account.
[code language="javascript"]{ "email" : "[email protected]", "firstName" : "John", "lastName" : "Smith", "company" : "ABC Bank", "title" : "CEO", "status" : "ACTIVE" }
You can also retrieve your senders by making a GET request to: https://sandbox.onespan.com/api/account/senders?from=0&to=10. In my example, I chose to retrieve my first 10 senders. You can customize the query parameters to your liking. For more information on the available query parameters, head over to our documentation.
To update your sender, you will need your sender ID, which you can retrieve from the request above. Note that the email address cannot be updated once you’ve created your sender. You will need to create a new sender in this case. To update your sender, you make a POST request to https://sandbox.onespan.com/api/account/senders/{senderId} with the following JSON:
[code language="javascript"]{ "firstName" : "John", "lastName" : "Smith", "company" : "XYZ Bank", "title" : "CEO", }
Similarly, you will also need the sender ID to delete your sender. If your sender has packages in their inbox or in draft status, the sender will be locked instead of being deleted, and will not be able to create or send packages. To delete your sender, you will need to DELETE request to: https://sandbox.onespan.com/api/account/senders/{senderId}.
Finally, here is a sample JSON on how you would build a document package to be sent by a particular sender from your account:
[code language="javascript"]{ "sender": { "email": "[email protected]" }, "documents": [ { "extract": true, "name": "Contract" } ], "status": "DRAFT", "roles": [ { "id": "contractor", "type": "SENDER", "signers": [ { "email": "[email protected]", "firstName": "John", "lastName": "Smith", "id": "contractor" } ], "name": "contractor" }, { "id": "client", "type": "SIGNER", "signers": [ { "email": "[email protected]", "firstName": "Mary", "lastName": "Doe", "id": "client" } ], "name": "client" } ], "type": "PACKAGE", "name": "Cleaning Contract Example" }
Running Your Code
You can now go ahead and run your code. You should be able to see your newly created sender(s) in your OneSpan Sign account, as mentioned in the "Senders in the UI" segment. For the Java and .NET SDKs, I’ve included the code that prints out the sender emails and ids. Below is a screenshot of what the output looks like.
If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://developer.onespan.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.
Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter
