Integrating with SIGNiX
Bringing SIGNiX Digital Signatures into Your Services
The SIGNiX Promise: A Great Integration with a High-Touch Approach
From our standpoint, a great integration includes several elements. The communication between SIGNiX and you must be clear, expectations well understood, and questions answered upfront. Your users must be happy with the final product, whether they be internal employees or external end users or clients. Sending documents for digital signatures must be as seamless as possible, with SIGNiX offering help and suggestions on user experience and key integration points based on best practices from our many existing successful implementations. And finally, you must be happy with the streamlined workflows, lowered costs, and higher revenue that can be achieved through the integration. Let us know if at any time you feel the integration process isn’t meeting those goals.
How can SIGNiX be integrated into your application?
The SIGNiX platform handles the end-to-end, complete process of multi-party digital transaction management to review, approve, and sign documents. The SIGNiX platform securely delivers to the parties all executed documents and legal evidence (audit trail), including tamper-evident or tamper-proof documents. The SIGNiX platform is available through our FLEX API that can even enable partners and customers to present the SIGNiX platform with their own branding (“private label”).
Once integrated, applications that need to capture digital signatures can send packages with documents, signers, identity verification / authentication, and workflows to SIGNiX. All interactions can be handled programmatically, minimizing customer / user interaction, and can be implemented in accordance with partner preferences, exposing some common interface elements but hiding others. SIGNiX offers unprecedented customization and embedding capabilities, allowing the customer to seamlessly fit user experiences, process functions, and other user interface elements to its high standards.
SIGNiX can send emails to signers and submitters to inform them of documents ready to be signed, while real-time push notifications automatically inform integrated systems that various events have taken place, allowing the triggering of other workflows in complementary systems.
An Application Programing Interface…effectively the tools and hooks by which your services will integrate with SIGNiX. The SIGNiX FLEX API is RESTful Web Services-based (which your developers should understand).
A Transaction is a set of one or multiple documents that can be digitally signed, acknowledged or reviewed by one or multiple signers and is submitted together for execution through SIGNiX.
Portable Document Format, aka ISO 32000-1. This is the document format that SIGNiX utilizes due to its capability to embed legal evidence, maturity and backwards compatibility. It must be AcroForm (most common format) and not XFA (Adobe LiveCycle).
This is a critical piece of evidence that captures every action and event that transpired during a transaction, including emails sent, identity authentications, signatures and other items. An audit trail is a separate record (in either PDF or XML format) that lets relying parties understand who interacted with any and all of the documents throughout a transaction lifecycle.
Systems integrated with SIGNiX will always first set up a transaction via this initial API call to our service. This call contains all of the information about how a transaction will be constructed: signers, authentication, documents, process, preferences, etc. SIGNiX then kicks off the transaction, although the context in which the notification for signature happens depends on the customer’s integration and user experience requirements.
Once a transaction is initiated with SubmitDocument, SIGNiX can deliver emails to all signers, or alternatively your system can prompt SIGNiX to generate a temporary signing link that can be presented to a signer or other client via a pop-up or button within your application.
Throughout the transaction lifecycle, these real-time alerts are sent from SIGNiX to your systems to notify them as various milestones occur, including, for example, when a signer completes all of his tasks or when they decide to opt out of using a digital signature, as well as notices of completed or expired transactions.
After a transaction has been completed, your system will send this API call to SIGNiX. Doing so retrieves completed, tamper-evident, signed PDFs as well as the audit trail (in PDF or XML format) for automated insertion into your document management or similar systems.
How can SIGNiX work with your business?
Other than a basic requirement for having documents electronically signed, the nature of the integration depends highly on how you plan to use SIGNiX. There are several key questions listed below that would be useful for you to optimize your utilization of SIGNiX.
What is the nature of the documents your organization wants to have signed?
This is one of the first questions to ask yourself so that you can understand how you’ll be using our service. Will you be sending one document to one person to sign, or will you send multiple documents to multiple signers? Will you need to have those signers fill in fields in the document? Do you need that data back outside of the PDF? How many documents will you need to send at a time? (Note that SIGNIX restricts PDF size to 10 MB and generally suggests no more than 10 documents in a transaction to optimize user experience.)
How will signers access their documents?
This will determine whether SIGNiX will handle emailing and notifying clients or if your system will handle it. Does your organization have a system that clients log into frequently that can be used to notify them their documents are ready to sign, or do you want SIGNiX to send emails to your clients? Are your signers external to your organization, or are they internal employees? Furthermore, will any of the signings be in-person? That is, will a signer present themselves physically in front of an employee or kiosk, for example, to review and sign a document?
Do you need to independently verify who the signers are?
This depends a lot on the risks you are managing as an organization. You may have regulatory requirements that require you to ‘authenticate’ a signer more strongly than just being able to click on a link in an email. SIGNiX has multiple options, including sending a one-time password via text message to a signer or prompting them to answer a series of dynamic, knowledge-based questions.
What are the systems that you will be integrating with SIGNiX?
Think about this like a race. You have a starting line, the course and a finish line. At the starting line, a transaction must be started and sent to SIGNiX. On the course, your system must be available to listen to updates from SIGNiX and notify other systems or individuals about the progress of the documents. At the finish line, your system must be able to retrieve and store the completed documents.
Who is starting the transaction?
Obviously, some action must start a transaction…will this be something automated in your systems based on a user clicking a button on a website, or will an internal employee use an existing application to kick off that signing process? How much interaction will be required by the employee? In other words, how much do you want to automate and how much do you want the employee to control?
How will you be storing the documents and audit trails?
When transactions are complete, SIGNiX expects that your organization will download the signed documents and store them in your own systems. In addition, for legal purposes, you should also download what’s called an audit trail (defined under Common Terms), which includes critical evidence to help verify a signed document if it is ever called into question. Therefore, your organization will need to understand where these signed documents and audit trails will be stored and ensure they remain accessible to the required individuals and systems.
Also note, SIGNiX does not generally store your signed PDFs indefinitely. We do have an archive policy, and those PDFs will no longer be readily available to your users from the SIGNiX platform after a 90 day period. SIGNiX can provide Unarchive Professional Services at our standard hourly rate if you have not requested that SIGNiX delete such documents. Dependent on your compliance/storage regulations, you may request to be placed on a custom deletion schedule (only after you’ve confirmed receipt will we purge our system of your data to limit copies of confidential documents).
Do you need any custom branding/emails?
SIGNiX can modify colors and logos, as well as other elements of our service to match up with the branding your organization uses. SIGNiX can also customize the emails that will be sent to signers, for a more personalized look that will match your company’s profile. Are these features something that would appeal to your clients?
What will your organization need to have in place to integrate with SIGNiX?
- Developer(s) must be fluent with XML, RESTful web services, Base64 encoding, secure integration principles and our FLEX API to ‘invoke’ it and build the integration.
- Your systems must have the ability to ‘tag’ PDF documents with Acroform (PDF) form fields (signature / text / etc.) or have pre-existing PDF forms with these fields on them that will be used by our system to let signers know where they will complete and sign a document.
- A ‘listener’ server must be set up by your team for use with push notifications. It can be the same server used for your system that triggers transactions or a separate one specifically for push notifications. This is described further below.
Taking Advantage of Push Notifications from SIGNiX
The SIGNiX system uses push notifications to notify your system in real-time as various milestones occur during a transaction’s lifecycle. These notifications are a critical part of your integration as they can be used to trigger other workflows in your organization or in other systems. A completed transaction may kickoff an account opening process, for example. Alternatively, if a user logs into your portal and fills out a form, you may want to prompt them to sign a release form immediately. And of course, as we suggested earlier, when a transaction is complete, your system will also trigger the DownloadDocument call to our system to retrieve the signed documents and audit trail.
To use push notifications, your system or organization needs to set up a ‘listener,’ which is a server that, you guessed it, is listening for messages from SIGNiX. When it receives an alert from SIGNiX, the server will send its own response back to SIGNiX, letting us know you received the message. This server should be robust enough to manage the traffic between SIGNiX and your systems and to respond to our requests within one second.
There are some additional requirements as well:
- A dedicated URL must be prepared to which SIGNiX will address the push notifications, along with a static IP address.
- Port 80 for HTTP (only allowed in test environment)
- Port 443 for HTTPS
- TLS 1.2
- Push notification response URLs must be secured via HTTPS in production.
- Clear our IP addresses to allow for traffic
- Your listener must respond with ‘OK’ and no other content.
- Your ‘listener’ must respond within 1000ms and before your system proceeds with other items in your flow.
Are there any requirements from SIGNiX before we go-live?
We want you and your clients to have a trouble-free experience once our joint solution becomes available for use. To make that happen, SIGNiX asks every organization that integrates with us to test multiple times, including a series of defined tests to insure a trouble-free user experience.
Access to a ‘test harness’ will be provided that includes sample code that can be used to test concepts and to build out your own integration. Use the test harness to try out different configuration and parameter changes prior to coding to better understand the implications.
- During testing:
- All email addresses used while operating in the SIGNiX test environment must resolve to real email addresses. Email addresses such as firstname.lastname@example.org, for example, will be flagged and not accepted.
- SubmitterName should be the name of the individual generating the transaction. SubmitterEmail must also be a real email.
- Authentication methods (ServiceType) should be carefully chosen based on consultation with SIGNiX and guidance from our documentation. Typically, the preferred authentication methods are SelectOneClick, SMSOneClick or KBAOneClick. If you believe your use case requires something different, please consult with your SIGNiX integration specialist.
- If you are using SelectOneClick or SMS OneClick, you should be testing using a dummy SSN data in the format "910000000" and for date of birth, "00/00/0000". For those authentication methods, we do NOT need and CANNOT use a signer’s real SSN or DOB during testing. If using KBAOneClick in our test environment, please create a 'fake' SSN starting with 3 zeroes and the remaining 6 digits as random numbers (do not use 000123456 but more like 000194782). Do NOT use actual SSN data.
- Your platform should generate at least 10-20 end-to-end tests once your integration has been completed before a Go-Live Review is scheduled with SIGNiX. These tests should be highly representative of a typical use case / scenario that would be encountered in production so we can be sure that the joint integrated system responds as we would expect it to in production. SIGNiX may assist you in providing a list of required tests so that we can produce a great integration result.
- A Go-Live Review meeting will be scheduled to demo the completed solution, confirm test results and manage the rollout timeline, as well as to discuss any of your open concerns or questions.
- A push notification listener and URL must be prepared.
Best Practices…and What Not to Do!
- Test early and often to head off integration issues later in the game.
- Set your authentication and client preference choices early in the integration process to ensure your integration goes smoothly and your relying parties are able to experience the integration as it will run in production.
- Apply use cases during integration and testing that are very similar, if not identical, to production use cases to ensure the best results.
- PDF signature fields should not be set to 'hidden.' Doing so will make the resulting signature not appear (thus hidden) on the final PDF.
- All transaction names should be unique as they will be shown to signers along the way and may be used to track information later. SIGNiX recommends, at the very least, including a signer’s first and last name, or some other identifier that is related to the use case. This could include an address, an account ID, etc. PDF names within a transaction should be unique but do not necessarily have to carry identifiers like a transaction name.
- Documents are not stored by our system for use during a SubmitDocument call. PDFs either have to be Base64 encoded and included in the XML submission for a SubmitDocument, or a URL needs to be provided from which SIGNiX can retrieve a PDF.
- PDF documents submitted to us for signing should already include fields that can then be referenced in the SubmitDocument call.
- If your platform allows a user to 'delete' transactions, those transactions should be completed and downloaded, or cancelled if in process. Other scenarios should be discussed with SIGNiX for best practices.
- DownloadDocument calls should only be made once the transaction has been completed, not during the process, to gain feedback for your workflow that you can use push notifications for.
We look forward to working with you to make your integration with SIGNiX a positive and effective experience. Our FLEX API integrations are powerful and robust, and we have many mature and proven integrations from which we will share best practices and suggestions to make your integrated solution the best that it can be. We are dedicated to your success and to ensuring an efficient, trouble-free integration leading to long term satisfaction by users, signers and IT professionals.