The business application uses SigningHub to provide document review and digital signature functionality. Users interact with the business web application and when they get to the point where a document requires approval SigningHub is invoked to display the document within an iframe. The user is unaware that SigningHub functionality is used. The user can review the entire document and sign in their defined location. Tight integration is suitable for ECM, CRM and ERP web applications or portals where a known user already interacts in a defined way. The user login information can be used by the business application to create and connect the user to their respective SigningHub account.
Using tight integration users interact with your web application and see the documents presented in an iframe/widget within your application web page. There is no website redirection and the user’s browser address bar does not change.
To achieve this, your web application executes some server side code and also an HTML code (inside an HTML iframe) which then renders the documents. Users can then view the documents, fill-in any form fields and create their signature (digital or electronic) whilst remaining on your site. This creates a simple, efficient and trustworthy experience for the user.
Using tight integration users interact with your web application and see the documents presented in an iframe/widget within your application web page. There is no website redirection and the user’s browser address bar does not change.
To achieve this, your web application executes some server side code and also an HTML code (inside an HTML iframe) which then renders the documents. Users can then view the documents, fill-in any form fields and create their signature (digital or electronic) whilst remaining on your site. This creates a simple, efficient and trustworthy experience for the user.
The HTML code, displayed inside the iframe, is delivered to your web application by a single API call. SigningHub provides an industry-standard RESTful API for simple integration.
The following image illustrates how the client web application interacts with SigningHub through API calls.
The process is:
With respect to security, and embedded iframes used by SigningHub for tight integration, the Integrations set-up allows you to specify the trusted domains of your business application. When you supply input variables under "Allowed Domains" SigningHub will create the appropriate Internet headers when the iframe is called by the business application. These are X-Frame-Options ALLOW-FROM for older browsers and CSP: frame-ancestors Header for the latest versions of Chrome for example.
The following image illustrates how the client web application interacts with SigningHub through API calls.
In this mode of integration, users interact with the business web application. At some point there is a need to view and sign a document. For ease of use, the user does not need to register or login in order to view and sign the document. In tight integration, the web application uses iFrame to embed the SigningHub view and sign page within an existing webpage.
The user’s signing field is highlighted for them, and clicking on it enables them to create their digital signature. All of these web service interactions are performed in a way that ensures the user has a seamless experience fully consistent with the existing business application.
When using tight integration, users do not login directly to the SigningHub and no email is generated by SigningHub. It is the business application’s responsibility to manage the workflow and keep the user informed.
Throughout this document, items in red are variables. To test all of the following commands without writing code, developers can use the POSTMAN Chrome plugin.
Throughout this document, items in red are variables. To test all of the following commands without writing code, developers can use the POSTMAN Chrome plugin.
The process is:
- Manual Step - an Enterprise Account must exist
- Manual Step - an Enterprise API Key, call back URL and application name must be configured
- Manual Step (Optional) - Enterprise Admin creates one or more workflow templates
- Manual Step (Optional) - add a document to your Enterprise Library which will be later sent to your user to sign. Alternatively, you can upload documents for signature using the APIs
- Coding (Optional) - the business application logs in as the Enterprise Admin and gets an admin access token (OAuth 2.0 access token) which is used for subsequent API authorisation
- Coding (Optional) - the business application creates a new Enterprise User
- Coding - the business application connects using the Enterprise User credentials and gets a user access token which is used to authenticate further actions to the users account
- Coding - the business application requests a new package within SigningHub
- Coding - the business application uploads a document to the Enterprise User account or adds one from their SigningHub Document Library
- Coding - the business application applies a template or dynamically add fields on the document
- Coding - the business application starts the document workflow
- Coding - the document is shown to the Enterprise User within an iframe
- Coding - the business application handles the call-back when user returns from iframe
- Coding - the business application checks the workflow status
- Coding - the business application downloads the signed package/document
The above steps assume that the business application requires digital signatures and for this, an Enterprise User is a prerequisite. When electronic signatures are required, there is no need to create an Enterprise User. In this case you simply:
- Skip step 6 and 7
- In all steps use the admin access token
- In step 11 use a special HTML tag e.g:
<input type="hidden" name="user_email" value="joe@gmail.com" />
These steps are explained in more detail here:
- Skip step 6 and 7
- In all steps use the admin access token
- In step 11 use a special HTML tag e.g:
<input type="hidden" name="user_email" value="joe@gmail.com" />
These steps are explained in more detail here:
Step 1 - Create an Enterprise Admin Account (Manual Step):
the business application has to connect to this account and make JSON requests to control the signing users/ recipients. The SigningHub cloud service www.signinghub.com can be used for testing and you can create a free Enterprise Admin account by clicking the FREE TRIAL button.
Step 2 - Generate the API Key (Manual Step):
Click here for instructions.
Step 3 - Create a Workflow Template (Manual Step, Optional):
Click here for instructions. If template can’t be used and you want to dynamically add fields then skip this step.
Step 4 - Add a Document to the Library (Manual Step):
If a standard document or contract is used you can avoid uploading the document programmatically for every use case. All you need is to maintain your document in your enterprise library and use the ID of the document as reference in your application. Click here for more information about managing documents in an enterprise library.
Step 5 - Authenticate Enterprise Admin via the API (Coding, Optional):
This call authenticates Enterprise Admin access to SigningHub so that an Enterprise User signer can be created. This requires the Enterprise Admin email address (username), password, API Key and Application Name. An OAuth 2.0 access token is returned. For authentication, the business application needs to send an HTTP POST request to SigningHub. This call is optional and needed if the call in Step 6 is needed. The following is an example request/response:
Sample Request
Sample Response
1) In the case where the business application creates the document dynamically then you can upload the document using the Upload Document API call explained here, as opposed to using a document from your respective library.
2) If you want to use a library document, then you can get the library document ID using Get Library Documents API.
Sample Request
Sample Response
the business application has to connect to this account and make JSON requests to control the signing users/ recipients. The SigningHub cloud service www.signinghub.com can be used for testing and you can create a free Enterprise Admin account by clicking the FREE TRIAL button.
Step 2 - Generate the API Key (Manual Step):
Click here for instructions.
Step 3 - Create a Workflow Template (Manual Step, Optional):
Click here for instructions. If template can’t be used and you want to dynamically add fields then skip this step.
Step 4 - Add a Document to the Library (Manual Step):
If a standard document or contract is used you can avoid uploading the document programmatically for every use case. All you need is to maintain your document in your enterprise library and use the ID of the document as reference in your application. Click here for more information about managing documents in an enterprise library.
Step 5 - Authenticate Enterprise Admin via the API (Coding, Optional):
This call authenticates Enterprise Admin access to SigningHub so that an Enterprise User signer can be created. This requires the Enterprise Admin email address (username), password, API Key and Application Name. An OAuth 2.0 access token is returned. For authentication, the business application needs to send an HTTP POST request to SigningHub. This call is optional and needed if the call in Step 6 is needed. The following is an example request/response:
Sample Request
|
https://api.signinghub.com/authenticate |
||
|
Verb |
POST |
|
|
Content-Type |
application/x-www-form-urlencoded |
|
|
Accept |
application/json |
|
|
Request Body |
grant_type=password& client_id=application_name& client_secret=API_Key& username=enterprise_admin_email& password= enterprise_admin_password |
|
Here, the application_name, and API_Key is taken from SigningHub > Enterprise menu > Integrations whereas enterprise_admin_email and enterprise_admin_password is your enterprise admin’s credentials.
Sample Response
|
Response Code |
Message | Response Body | |
|
200 |
OK |
{
access_token: "access_token_admin", |
|
The received access_token_admin is used in the register user call below.
The password field must be encrypted that is provided in request body, while integrating this within your business application.
Step 6 - Register an Enterprise User via the API (Coding, Optional):
This represents the user account that will sign the signature field identified in the Share Document request. An account for the signer must exist, if it does not then to create a signer, the business application needs to send the following example request only once. To learn more about each parameter used consult the API Reference here.
Sample Request
|
https://api.signinghub.com/v3/enterprise/users |
||
|
Verb |
POST |
|
|
Content-Type |
application/json |
|
|
Accept |
application/json |
|
| Authorization |
Bearer access_token_admin |
|
|
Request Body |
{ user_email: "john@ascertia.com", } |
|
Sample Response
|
Response Code |
Message | Response Body | |
|
201 |
Created |
{ } |
|
Step 7 - Authenticate Enterprise User (Coding):
This authenticates access to SigningHub and requires the Enterprise User email address (username) and the password, plus the API Key and Application Name. An OAuth 2.0 access token is returned. For authentication, the business application needs to send an HTTP POST request to SigningHub. The received access token is then used at document view and sign time. Following is an example request/response:
This authenticates access to SigningHub and requires the Enterprise User email address (username) and the password, plus the API Key and Application Name. An OAuth 2.0 access token is returned. For authentication, the business application needs to send an HTTP POST request to SigningHub. The received access token is then used at document view and sign time. Following is an example request/response:
Sample Request
|
https://api.signinghub.com/authenticate |
||
|
Verb |
POST |
|
|
Content-Type |
application/x-www-form-urlencoded |
|
|
Accept |
application/json |
|
|
Request Body |
grant_type=password& client_id=application_name& client_secret=API_Key& username=enterprise_admin_email& password= enterprise_admin_password |
|
Here application_name, API_Key is taken from SigningHub > Enterprise menu > Integrations whereas enterprise_user_email and enterprise_user_password is your enterprise user’s credentials set in the previous call.
Sample Response
|
Response Code |
Message | Response Body | |
|
201 |
OK |
{
access_token: "access_token_user", |
|
Step 8 - Add Package (Coding):
This service API is used to create a blank document package, used to hold individual documents. Documents are added to the package and prepared in order to start a workflow.
This service API is used to create a blank document package, used to hold individual documents. Documents are added to the package and prepared in order to start a workflow.
Sample Request
|
https://api.signinghub.com/v3/packages |
||
|
Verb |
POST |
|
|
Content-Type |
application/json |
|
|
Accept |
application/json |
|
| Authorization | Bearer access_token_admin |
|
|
Request Body |
{ package_name: "New Package" } |
|
Sample Response
|
Response Code |
Message | Response Body | |
|
200 |
OK |
{
package_id: 123 |
|
Step 9 - Add Document (Coding):
Business applications can use this service API to add a document from the user’s library to a package. The package_id is provided in the URL which should be the same as found in the previous call. The document ID must be provided as document_id in the resource URL to identify the library document to be copied.
Business applications can use this service API to add a document from the user’s library to a package. The package_id is provided in the URL which should be the same as found in the previous call. The document ID must be provided as document_id in the resource URL to identify the library document to be copied.
Sample Request
|
https://api.signinghub.com/v3/packages/{package_id}/documents/library/{document_id} |
||
|
Verb |
POST |
|
|
Content-Type |
application/json |
|
|
Accept |
application/json |
|
| Authorization | Bearer access_token_user |
|
|
Request Body |
{ } |
|
Sample Response
|
Response Code |
Message | Response Body | |
|
200 |
Created |
{ document_id: document_id_new, enabled: true }, template: {
|
|
1) In the case where the business application creates the document dynamically then you can upload the document using the Upload Document API call explained here, as opposed to using a document from your respective library.
2) If you want to use a library document, then you can get the library document ID using Get Library Documents API.
Step 10 - Apply Template or dynamically add fields (Coding):
Business applications can use this service API to apply a workflow template to a document. The document ID on which template has to be applied is provided in the resource URL. In this call the package_id should be same as used in step 9 and the document_id_new is the one the user got in the response of step 9.
Business applications can use this service API to apply a workflow template to a document. The document ID on which template has to be applied is provided in the resource URL. In this call the package_id should be same as used in step 9 and the document_id_new is the one the user got in the response of step 9.
Sample Request
|
https://api.signinghub.com/v3/packages/{package_id}/documents/{document_id_new}/template |
||
|
HTTP Verb |
POST |
|
|
Content-Type |
application/json |
|
|
Accept |
application/json |
|
| Authorization | Bearer {access_token_user} |
|
|
Request Body |
{ template_name: "sales contract template", apply_to_all: true } |
|
Sample Response
|
Response Code |
Message | Response Body | |
|
200 |
OK |
{ document_id: 123, document_name: "sales contract 105", document_order: 1, document_type: "PDF", document_source: "My App", document_width: 600, document_height: 800, document_pages: 12, uploaded_on: "2015-01-12T11:12:13", modified_on: "2015-01-13T10:10:15", form_fields: true, lock_form_fields: true, certify: { enabled: true permission: "FORM_FILLING_ALLOWED" }, template: { template_name: "Sales Contract Template", read_only: true }, }
|
|
In the case where the template contains a placeholder or a user that you wish to change then you can use the Update Workflow User API call as explained here. Alternatively if due to the dynamic nature of the document you cannot apply a template and want to add different fields, e.g. text field, checkbox, initials, signature fields etc., then you can add them dynamically by providing the X, Y, Width, Height coordinates, package ID, document ID, page number and assign to a user. Click here to learn more.
Step 11 - Share Package (Coding):
Business applications can use this service API to share a document with the designated signatories and start a new workflow. The document should already have been prepared by optionally applying a template and optionally updating the users and actions defined in template. The package ID to be shared is provided in the resource URL. In this call the package_id should be same as used in step 9 above.
Sample Request
Step 11 - Share Package (Coding):
Business applications can use this service API to share a document with the designated signatories and start a new workflow. The document should already have been prepared by optionally applying a template and optionally updating the users and actions defined in template. The package ID to be shared is provided in the resource URL. In this call the package_id should be same as used in step 9 above.
Sample Request
|
https://api.signinghub.com/v3/packages/{package_id}/workflow |
||
|
Verb |
POST |
|
|
Content-Type |
application/json |
|
|
Accept |
application/json |
|
| Authorization | Bearer access_token_user |
|
|
Request Body |
||
Sample Response
|
Response Code |
Message | Response Body | |
|
200 |
Created |
[{ package_id: 12, documents: [123, 124, 125] }, { package_id: 13, documents: [123, 124, 125] }, { package_id: 14, documents: [123, 124, 125] }]
|
|
The instructions above constitute a minimal but functional JSON request to SigningHub. To get in-depth details refer to the API Reference manual.
Step 12 - Generate Integration URL for Encrypted Data (Coding):
Business applications can use this service API to generate an encrypted URL to access a document and to perform signing operation on that document. The returned URL in response will be an encrypted URL which contains all the information which was provided in request body. See sample request below.
Sample Request
If you want to load SigningHub in your language then ensure you pass the correct language information e.g. en-US, de-DE etc. SigningHub supports 20+ languages.
if an authentication token was acquired with the scope parameter the iframe will be redirected to the SigningHub login screen for manual authentication from the end user himself. The user must know his email address and password to login into the system and sign the document. Single-Sign-On (SSO) is configured with a non-SigningHub authentication mechanism, e.g. Salesforce, Office365, ADFS. If the user is already signed in into any of these applications, the SigningHub authentication will not prompt for the user password again.
Step 13 - Handle Call-back (Coding):
Once the user has signed, declined or reviewed and approved the document within the SigningHub document viewer, the user can close the document and return to the web application. When the user closes the document, SigningHub immediately returns control to the web application using the configured URL for that specific integration. This is the 'call-back' parameter, configured under the Application Integration settings. To edit this, and all integration options, login to SigningHub as the Enterprise Admin and navigate to: Enterprise Settings > Integration > Application Integration. Furthermore, call-back URL can also be provided within the HTML code snippet as shown above, in this case the provided call-back would have priority. However this parameter is optional, if not provided then call-back URL set inside Enterprise Settings > Integration > Application Integration would be followed.
Control is returned to the web application as soon as the user navigates away from the document viewer window. For cases such as signature operations this occurs when the user completes the signing process and clicks on 'Finish' button. Browser navigation (back button) is another way of navigating away from the document viewer and will also result in control passing back to the web application, and invoke the call-back URL. When control returns to the web application, SigningHub appends the following parameters to the call-back URL to inform the web application of the action status:
Step 12 - Generate Integration URL for Encrypted Data (Coding):
Business applications can use this service API to generate an encrypted URL to access a document and to perform signing operation on that document. The returned URL in response will be an encrypted URL which contains all the information which was provided in request body. See sample request below.
Sample Request
|
https://api.signinghub.com/ v3/links/integration |
||
|
Verb |
POST |
|
|
Content-Type |
application/json |
|
|
Accept |
application/json |
|
| Authorization | Bearer access_token_user |
|
|
Request Body |
{ package_id:"12345", language:"en-US", user_email: "joe@gmail.com", callback_url:"https://web.signinghub.com/", collapse_panels: "true", usercertificate_id: "31585" } |
|
Sample Response
|
Response Code |
Message | Response Body | |
|
200 |
OK |
"https://web.signinghub.com/Integration?q=QUVTMjU2LUdDTTm7sHn5UnS-2B-MB9OYT4MM4iHd4nGT-2B-3lkpLq-2B-15xg8av10bU807OEkv9fOc7jm1wsnDS1aAxCAUhEkrxup3BVNMknwQPgMGHlAAE4tdR8MbbBzbF8”
|
|
The instructions above constitute a minimal but functional JSON request to SigningHub. To get in-depth details refer to the API Reference manual.
If you want to load SigningHub in your language then ensure you pass the correct language information e.g. en-US, de-DE etc. SigningHub supports 20+ languages.
<html> <body> <!-- Your Web Application Header Here --><iframe id="id_sh_iframe" name=" sh_iframe" width="100%" height="100%"src=https://web.signinghub.com/Integration?q=QUVTMjU2LUdDTV6zwGuNqpNNIOqrQtz0WRwPC5B-2F-PYd-2B-0EkqpT5C6JxzABo4Js0-2B- ngad2q3o3zTBmTLpTdWxHybLRakyTsgMLEC6OOxMSlqC612rr1QgfBxOPqeyubHzgNmcE22w6f-2B-xEmbomY4-2F-2TSUj92ROfQhZg-2F- JWQ3vwXMzmTjXQsheSJzJaMNuULbyik50fDWyY8oNVx31G2tiU8-2B-3W7emvEPMWtebqZFefK9icLjonwATdZfkfUKk4f8qxapEsnbwxnk24W6qb0QIXQYnw3aOIqqLowJFzlOX- 2F-ZIkdAoggLWzHXUNKeSC9bwfBvZumXU-2B-BIztM5kEAAPWHEXXNLB3bY8rrbmkYzXhMArGJRuP0L1F1jzamG0EsgW4me-2F-FpVQL6YQSLtoOpH-2B- pQMWh7pV3U2xVIY1mqvNsoGwTW3ZJQBvmZl3qMjUITnBYNxpx9WgHjxSCkLHZSp1fMjdqOyg3-2B-lY2fyV8ogpLZFXEEr-2B- vatyNbE8ogAZDay8pec6bFA7YsA2FyuZFCMvHif9hD510- 2F-Jd7Kxs9HmyjsaRJhWGu6kb9BhfFl-2F-4ROZqz3TpVSXRW-2F-wXcIj07Imq-2F- 6zEdP4NRDI2wmJbpuZk8ZMuf6yeyjTGswhVlW-2F-Js-2B-vm0aQuUSjcJKm3FZbhhwcFQWaOubyS9ZYlbjdCBavSwSHOC2N2LYC6PpxFRBWquKBL6JXy1DbVDTc3-2B--2F- RK4SrP0RH0gf3oHZHBaJtdWX1WgbkJEmfUneKQ5RzgP9AH4F4Crrfr65jCKZhWfj2cjMglT54V0igjo4nLmk2pWlmdWn3pEkQ6v4SLH3tuiQQCcVjtL96STJwBykMoAN-2F- CCdQjOSuz8toX23cO7eO0ZtkF3rHNHkfc0lQaiM0y8FPrwrKiBdXOFavUwNq-2F-ZlklgHjHTOAI1A7Z7v9wyTW3f4uNRR6Em0NJupJO0rvriX8unl7q-2F- 9FzyFutfwRe95cedcglV/> <!-- Your Web Application Footer Here --> <body></html>
If the business application requires electronic signatures, then as explained previously, there is no need to create Enterprise Users. Hence, in the above web service request body simply provide parameter value under ’user_email’ (e.g. joe@gmail.com). Here the value is the email address of user who is going to process the document.
user_email: “joe@gmail.com”if an authentication token was acquired with the scope parameter the iframe will be redirected to the SigningHub login screen for manual authentication from the end user himself. The user must know his email address and password to login into the system and sign the document. Single-Sign-On (SSO) is configured with a non-SigningHub authentication mechanism, e.g. Salesforce, Office365, ADFS. If the user is already signed in into any of these applications, the SigningHub authentication will not prompt for the user password again.
Step 13 - Handle Call-back (Coding):
Once the user has signed, declined or reviewed and approved the document within the SigningHub document viewer, the user can close the document and return to the web application. When the user closes the document, SigningHub immediately returns control to the web application using the configured URL for that specific integration. This is the 'call-back' parameter, configured under the Application Integration settings. To edit this, and all integration options, login to SigningHub as the Enterprise Admin and navigate to: Enterprise Settings > Integration > Application Integration. Furthermore, call-back URL can also be provided within the HTML code snippet as shown above, in this case the provided call-back would have priority. However this parameter is optional, if not provided then call-back URL set inside Enterprise Settings > Integration > Application Integration would be followed.
Control is returned to the web application as soon as the user navigates away from the document viewer window. For cases such as signature operations this occurs when the user completes the signing process and clicks on 'Finish' button. Browser navigation (back button) is another way of navigating away from the document viewer and will also result in control passing back to the web application, and invoke the call-back URL. When control returns to the web application, SigningHub appends the following parameters to the call-back URL to inform the web application of the action status:
| Append Parameters | |
| Name |
Description |
| package_id | The ID of the package that was used to generate integration URL for encrypted data and shown to the user in call back URL. |
| action |
Provides information about the action the user performed on the document. The possible values are:
|
Step 14 - Check Workflow Status (Coding):
Once the document has been shared and the workflow is in progress, the document owner may want to see the current status of the workflow. The status of workflow at any time can be checked by using the Get Workflow Details API. Click here for details.
Step 15 - Download Package/Document (Coding):
- If the workflow consists of multiple documents, then you can use the Download Package API call to download the package as a zip file as explained here.
- If the workflow consists of just a single document, then the business application can download the signed document using the Download Document API call as explained here.