SigningHub API Guide

Download OpenAPI specification:Download

Welcome

Welcome to SigningHub, a high trust digital signing solution for all your paperless business transactions. It is ideal for those organisations that recognise the value of using cryptographic digital signatures to protect their users and their documents against unauthorised or accidental or fraudulent changes.


Browse through the API content by selecting the relevant pages from the left panel. To quickly find specific web service information, enter search criteria in the search box on top left. .

More about SigningHub
To know more about SigningHub, explore the following links:
  • Go to  SigningHub Knowledge Base to view all the relevant information of SigningHub.
  • Contact SigningHub support staff through the  Live Chat provision Our support staff may be occupied with other priority tasks so live chat is offered on an "as available" basis. 
Intended Readership
This guide is intended for developers who will integrate SigningHub into their respective web web applications using the RESTful web services, and user interface offered by SigningHub. It is assumed that the reader has a basic knowledge of REST, Java, C#, HTML, JavaScript, HTTP and TLS/SSL. There is no Software Developers Kit (SDK) for the integration, instead the integration uses HTML Forms and JSON so that integration is simple from any language including .Net, Java, PHP etc.

Most Popular Pages
Authentication
Account Management
Add Package
Upload Document
Get Workflow Details
Sign Document

Prerequisites

To access SigningHub via RESTful API a suitable Enterprise Admin account and API key is required.  An  Enterprise Admin can generate a unique API key to identify your application. Authentication uses the Enterprise Admin (or alternatively Enterprise User) and associated API key to generate an OAuth 2.0 bearer token. This token is then required for authorisation for all API calls.

  1. Create an Enterprise Admin account  – the business application has to connect to this account and makes JSON requests to control the signing users/recipients. The SigningHub cloud service can be used for testing and you can create a free Enterprise Admin. Once you have created the account, contact Ascertia support (support@ascertia.com) and provide the name of your enterprise to have the standard restrictions removed from your account, to allow you to fully test the web services integration option.  This restriction is for number of signatures, workflows, and templates. .

  2. Create an API Key  – set an Application Name, Call-back URL and generate an API Key in SigningHub, using the Enterprise Settings menu > Integrations screen. Note the Application Name and API Key.  See details, how to configure an API key.

  3. Create workflow templates (Optional)   the workflow template defines the location of each signature field and the user that is expected to sign the document. It also defines other document and workflow control options including PDF permissions, the ability to download or print document for example. Templates may increase efficiency, especially when a standard contract or agreement is used many times. SigningHub also supports dynamic creation of signature fields for use cases where documents are created and uploaded in real time where templates may not be appropriate. .
It is important to understand that you know what type of signature you require.  That is basic electronic versus digital.  Digital signatures have more legal weight but in terms of SigningHub it means every signatory must have a SigningHub account.  Conversely, for lower value/less sensitive transactions, electronic signatures may suffice, and in those use cases it is not necessary to create a SigningHub account for every signatory.  Thus, the coding implementation differs dependent upon the signature type required.  In terms of tight and loose integration this is the difference between end users having to authenticate to SigningHub or not.

Migration

If you have been using legacy APIs version V3 and you are migrating your business applications from V3 to V4, following are the details of the changes that have been introduced in the version v4.

Enterprise

Below are the APIs that are affected by the change.

Add Certificate

V3 (Update Certificate) V4 (Update Certificate)
From 779, SH has introduced the Level of Assurance and Key Protection Option that has to be provided against each capacity and has to be provided at the time of adding capacity.

For Backward Compatibility (In-Database)

  • While adding custom capacity using V3, below values will be added by default

    • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE",
    • "key_protection_option": "REMOTE_AUTHORISATION",

Two new parameters added

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE",
  • "key_protection_option": "REMOTE_AUTHORISATION",

Update Certificate

V3 (Update Certificate) V4 (Update Certificate)
From 779, SH has introduced Level of Assurance and Key Protection Option that has to be provided against each capacity but at the time of updating a capacity, only its level of assurance can be updated.

For Backward Compatibility (In-Database)

  • While updating custom capacity using V3, the below values will be added by default

    • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

New parameters added

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

Document Preparation

Below are the APIs that are affected by the change

Add Digital Signature Field

V3 (Add) V4 (Add)

From 779, Digital Signature Field has been replaced by with Signature Field, and which capacity should be used at the time of signing is controlled via the level of assurance.

  • If User owned certificates are required to be used then use: ADVANCED_ELECTRONIC_SIGNATURE, HIGH_TRUST_ADVANCED, and QUALIFIED_ELECTRONIC_SIGNATURE

  • If Company Owner Certificates are required to be used then use: ELECTRONIC_SEAL, ADVANCED_ELECTRONIC_SEAL, and QUALIFIED_ELECTRONIC_SEAL

For Backward Compatibility (In-Database)

  • While adding the digital signature field using V3, the below values will be added by default that will be considered as Digital signature

    • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

New parameters added

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

Update Digital Signature Field

V3 (Update) V4 (Update)

From 779, Digital Signature Field has been replaced by with Signature Field, and which capacity should be used at the time of signing is controlled via the level of assurance.

  • If User owned certificates are required to be used then use: ADVANCED_ELECTRONIC_SIGNATURE, HIGH_TRUST_ADVANCED, and QUALIFIED_ELECTRONIC_SIGNATURE

  • if Company Owner Certificates are required to be used then use: ELECTRONIC_SEAL, ADVANCED_ELECTRONIC_SEAL, and QUALIFIED_ELECTRONIC_SEAL

For Backward Compatibility (In-Database)

  • While adding the digital signature field using V3, the below values will be added by default that will be considered as Digital signature

    • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

New parameters added

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

Add Electronic Signature Field

V3 (Add Electronic) V4 (Add Electronic)

From 779, Electronic Signature Field has been replaced by with Signature Field, and which capacity should be used at the time of signing is controlled via the level of assurance.

  • The authentication tag will be ignored by the system.

For Backward Compatibility (in Database)

  • While updating the electronic signature field using V3, the below values will be added by default that will be considered as Electronic signature

    • level_of_assurance": "ELECTRONIC_SEAL"

New parameters added

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE",

Update Electronic Signature Field

V3 (Update Electronic) V4 (Update Electronic)

From 779, Electronic Signature Field has been replaced by with Signature Field, and which capacity should be used at the time of signing is controlled via the level of assurance.

  • The authentication tag will be ignored by the system.

For Backward Compatibility (in Database)

  • While updating the electronic signature field using V3, the below values will be added by default that will be considered as Electronic signature

    • level_of_assurance": "ELECTRONIC_SEAL"

New parameters added

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

Add In-Person Signature

V3 (Add) V4 (Add)

From 779, Authentications have been removed from In-person signatures.

if any of the authentications are applied then it will not work and neither will be saved in the database.

Update In-Person Signature

V3 (Update) V4 (Update)

From 779, Authentications have been removed from In-person signatures.

if any of the authentications are applied then it will not work and neither it will save in the database.

Assign Document Field

V3 (Assign) V4 (Assign)

From 779, At the time of field assignment, the client has to define which capacity will be used to sign the existing signature field that is controlled via the level of assurance.

  • If User owned certificates are required to be used then use: ADVANCED_ELECTRONIC_SIGNATURE, HIGH_TRUST_ADVANCED, and QUALIFIED_ELECTRONIC_SIGNATURE

  • if Company Owner Certificates are required to be used then use: ELECTRONIC_SEAL, ADVANCED_ELECTRONIC_SEAL, and QUALIFIED_ELECTRONIC_SEAL

For Backward Compatibility (in Database)

  • While adding the digital signature field using V3, the below values will be added by default that will be considered as Digital signature

    • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

New parameters added

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE",

Get Document Fields

V3 (Get) V4 (Get)

From 779, All signature fields (Digital Signature, Electronic Signature) have been replaced with Signature fields and the level of assurance defines which capacity will be used to sign the field.

  • Hand Signatures have been removed from the system so will not be available

  • All of the hand signatures will be shown in electronic signatures

  • This will not have any effect on signing time as all hand signatures will be signed as Annotation.

All of the Digital Signatures and electronic signatures will be shown under the Signature tag with the level of assurance.

AutoPlace API

V3 V4

From 779, At the time of field assignment, the client has to define which capacity will be used to sign the existing signature field that is controlled via the level of assurance.

  • If User owned certificates are required to be used then use: ADVANCED_ELECTRONIC_SIGNATURE, HIGH_TRUST_ADVANCED, and QUALIFIED_ELECTRONIC_SIGNATURE

  • If Company Owner Certificates are required to be used then use: ELECTRONIC_SEAL, ADVANCED_ELECTRONIC_SEAL, and QUALIFIED_ELECTRONIC_SEAL

  • For Backward Compatibility (in the database)

    • Digital Signature will be added as

      • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE"

    • An electronic signature will be added as

      • level_of_assurance": "ELECTRONIC_SEAL"

New parameters added

  • "field_type": "SIGNATURE",

  • level_of_assurance": "ADVANCED_ELECTRONIC_SIGNATURE",

Document Workflow

Below are the APIs that are impacted

Update Workflow User Authentication

V3 V4

From 8.0 onwards, Update workflow authentication will be used to apply signing authentications for the Guest user.

New parameters added

  • "authenticaiton_signing": "",

  • "enabled": "true|false", "sms_otp": "",

Document Processing

Below APIs are impacted

Sign Document

V3 V4

From 8.0 onwards, Signing Servers need to be sent with the request to identify which server is being used to sign.

  • Authentication needs to be filled if the role required authentication.

  • if there is one signing server in the service plan then things will work without change

  • if in case there are multiple signing servers then the system will generate an Error *

New parameters added

  • "signing_server": "",

  • "authentication",

Account Management

Below APIs are impacted

Get User Role

V3 V4
  • Signing Servers added in response that will be shown at the time of signing signature field.

  • Digital Signature Field / Electronic Signature Field has been replaced by with Signature Field will be returned in response

Personal Settings

Below APIs are impacted

Get Signature Settings

V3 V4
  • Signing Servers added in response that will be shown at the time of signing signature field.

Access Tokens

Supported Tokens

This section provides information of supported tokens by SigningHub.

  • Client Credentials Token - The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user. This is typically used by clients to access resources about themselves rather than to access a user's resources. The business application should use client credentials token to authenticate themselves and to manage an enterprise or use scope token API to perform actions on behalf of the user. Click here for more details
  • User Credentials Token - The Password grant type is a way to exchange a user's credentials for an access token. This is typically used to access users' resources like upload, share, etc. Enterprise Actions should be allowed in the user's role to manage them. Click here for more details
  • Scope Token - The business application uses scope API to create a token that then allows the business application to perform actions on behalf of the users. This will require a business application to be authenticated first.Click here for more details

Below is the list of APIs that provdes information of which api is allowed to be used by token.

  • shows that API is supported
  • (-) shows that API is not supported
Section API Client Credentials User Credentials Client Credentials with User as Scope
Authentication Password Authentication
Kerberos Authentication
Single Sign On Authentication - -
OTP Login Authentication - -
Pre Login Authentication - -
Get Service Agreements - -
Get Public Authentication Profiles - -
Logout - -
Revoke Refresh Tokens - -
Scope Authentication - -
Document Package Add Package -
Get Packages -
Rename Package -
Share Document Package -
Change Document Package Owner -
Open Document Package - -
Close Document Package - -
Download Package Base64 -
Download Package Bytes -
Get Package Verification - -
Delete Package -
Upload Document Base64 -
Upload Document Stream -
Upload document from Library -
Apply Workflow Template -
Get Certify Policy for a Document -
Update Certify Policy for a Document -
Rename Document -
Download Document -
Download Document(Base64) -
Get Document Details -
Get Document Image - -
Get Document Image (Base64) - -
Get Document Verification - -
Change Document Order -
Delete Document -
Upload XML StyleSheet (.XSLT) -
Upload XML StyleSheet (.XSLT) Base64 -
Document Workflow Get Workflow User Permissions of Enterprise Package -
Update Workflow User Permissions of Enterprise Package -
Get Attachments - -
Upload Attachment - -
Download Attachment - -
Download Attachment (base64) - -
Delete Attachment - -
Mark as Read Workflow Comments -
Get Workflow Details -
Update Workflow Details -
Update Post Processing -
Get Workflow Reminder -
Update Workflow Reminders -
Get Workflow History -
Get Workflow History Details -
Get Certificate Saved In Workflow History -
Complete Workflow in the Middle (Terminate Workflow) -
Get Process Evidence Report - -
Get Workflow Users -
Add Users to Workflow -
Add Groups to Workflow -
Add Placeholder to Workflow -
Update Placeholder -
Update Workflow User -
Update Workflow Users Order -
Update Workflow Group -
Delete Workflow User -
Get Workflow User Permissions -
Update Workflow User Permissions -
Get Workflow User Authentication (Document Opening) -
Update Workflow User Authentication(Document Opening) -
Open Document via Password - -
Open Document via OTP (Generate) -
Add Workflow Comments -
Get Workflow Comments -
Add shared space -
Get shared spaces -
Delete shared space -
Get shared space -
Update shared space -
Get shared space Documents -
Move Package to Custom/Shared Space folder -
Document Preparation Get Document Fields -
Auto placeFields -
Assign Document Field -
Delete Document Field -
Add Digital Signature Field -
Update Digital Signature Field -
Add In-person Field -
Update In-Person Field -
Add Initial Field -
Update Initial Field -
Add Checkbox Field -
Update Checkbox Field -
Add Textbox Field -
Update Textbox Field -
Add Radiobox Field -
Update Radiobox Field -
Add QR code -
Update QR code -
Document Processing Recall Document -
Approve Document - -
GateKeeper Approve Document - -
Decline Document - -
GateKeeper Decline Document - -
Finish Processing - -
Submit Document - -
Signer Authentication Via OTP (Users, In-Persons, E-Signers) -
OTP Bulk signing Authentication - -
Sign Document - -
Bulk Sign Packages - -
Pre validate bulk signing - -
Bulk Signing Status - -
Fill Form Fields - -
Fill Initials - -
Get Registered Devices - -
Authorization Signing Request Status - -
      User Credentials
(with Allowed in Role)
 
Enterprise Management Register Enterprise User -
Get Enterprise Users -
Update Enterprise User -
Delete Enterprise User -
Add Enterprise user Signing Certificates -
Update Enterprise user Signing Certificates -
Delete Enterprise user Signing Certificates -
Get Enterprise Invitations - -
Delete Enterprise User Invitation - -
Get Groups - -
Add Enterprise Group - -
Get Enterprise Group - -
Update Enterprise Group - -
Delete Enterprise Group - -
Get Enterprise Branding Logo - -
Get Enterprise Branding Favicon - -
Get Enterprise Packages - -
Get Enterprise Package - -
Delete Enterprise Package
Complete Enterprise Package in the Middle (Terminate Workflow) - -
Add Enterprise legal notice -
Update Enterprise legal notice -
Delete Enterprise legal notice -
Get Enterprise Legal Notice -
Get Workflow Users For Enterprise - -
Update Workflow User of enterprise Package -
Update Placeholder of enterprise Package -
Update Workflow Group of enterprise Package -
Reset Enterprise Emails To Default - -
Account Management Add Feedback - -
Get Account Invitations -
Accept Account Invitation - -
Reject All Account Invitations - -
Register User (Free Trial) Yes(Only Client MSOfficeApp, and MobileSDK is allowed) - -
Get Account - -
Resend Activation Email -
Account Usage Statistics - -
Documents Statistics - -
Get Account Password Policy - -
Get User Role - -
Device Registration for Push Notifications - -
Add Identity for a User - -
Get User Activity Log Details - -
Get User Activity logs - -
Get Notifications - -
Change Password - -
Reset Password -
Set New Password -
Send Forgot Password Request -
Personal Settings Remove Account Request - -
Remove Account - -
Get Library Documents - -
Get Delegation Settings - -
Update Delegation Settings - -
Get General Profile Information - -
Update General Profile Information - -
Get Profile Picture - -
Get Profile Picture (Base64) - -
Update Profile Picture - -
Update Locale Settings - -
Update Security Settings - -
Get Signature Settings -
Get Hand Signature Text For Web - -
Get Initials For Upload Option - -
Get Hand Signature Upload For Mobile - -
Get Hand Signature Upload For Web - -
Get Initials for Text Option - -
Get Hand Signature Text For Mobile - -
Get Signature Appearance - -
Update Initial Appearance - -
Update Hand Signature(Browser) - -
Update Signature Appearance Design - -
Update Hand Signature(Mobile) - -
Update Signature settings Metadata - -
Get Templates - -
Reset User Emails To Default - -
Get Groups - -
Add Personal Group - -
Get Personal Group - -
Update Personal Group - -
Delete Personal Group - -
Get Contacts - -
Add Contact - -
Add personal Legal Notice -
Update personal Legal Notice -
Get Legal Notices -
Get Personal Legal Notice -
Delete Personal Legal Notice -
General OTP Verification - -
Get Profile Picture of Recipient -
About SigningHub AllowAnonymous   -
System Settings -
Get Languages -
Get SigningHub Admin Branding -
Get SH Admin Branding Logo -
Get SH Admin Branding Favicon -
SigningHub Admin APIs Admin Authentication      
Create Account      
Change User Service Plan      
Get Accounts      
Service Plan Reset      

Quick Integration

This section provides a quick "Do this and it works" guide for developers to understand how they can integrate SigningHub features within their business applications.

Overview

SigningHub exposes an external communication channel that allows external business applications to authenticate themselves, send requests and receive responses. This integration can be done with an on-premise instance (or private cloud instance) or the public cloud service running here www.signinghub.com.

The business application uses a secure HTTPS session to pass the document and its workflow control data to SigningHub. Using this approach, SigningHub can quickly and easily integrate with business applications to provide users with document review and digital signature approval functionality.

There is no Software Development Kit (SDK) for the integration, instead, SigningHub provides REST APIs that simplify the integration and can be used with any language including .Net, Java, PHP, etc.

Integration Scenarios

There are two ways to integrate SigningHub within a business application:

  • Tight Integration - 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 it 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.
  • Loose Integration - The business application sends a document to SigningHub together with control information. SigningHub creates and manages the workflow and emails each user in turn prompting them to log in, review and sign the document. Users log in and see the document within the SigningHub view and sign screen. They can review the entire document and sign in their defined location. This mode is most suitable for integration with a back-office application that has no exposed public-interface

    This Quick Guide summarises how to use tight integration. The SigningHub software includes an example tight integration demo website built in .NET to help developers with web application/portal integration.

Tight Integration

The following diagram summarizes the process for tight integration:

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 technology to embed the SigningHub view and sign page within an existing webpage.

The user’s signing field is highlighted for them, and clicking on such 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.

The process is:

  1. (Manual Step) - an Enterprise Account must be created
  2. (Manual Step) - an Enterprise Client ID, Client Secret and Call back URL must be configured
  3. (Manual Optional Step) - the Enterprise Admin creates a workflow template
  4. (Manual Optional Step) - the Enterprise Admin uploads a document to Enterprise Library which will be later sent to your user to sign
  5. (Coding) - the business application gets a client credential access token which is then used to get scope token
  6. (Optional coding) - the business application registers a new Enterprise User
  7. (Coding) - the business application gets a scope token using client credentials access token which is used for subsequent API calls
  8. (Coding) - the business application uploads a new package to the Enterprise User (used as Scope) account
  9. (Coding) - the business application applies a template or dynamically adds fields to the document
  10. (Coding) - the business application starts the document workflow
  11. (Coding) - the document is shown to the Enterprise User (used as Scope) within an iframe
  12. (Manual) - the enterprise user review and signs the document within an iframe
  13. (Optional coding) - the business application downloads the package/document

These steps are explained in more detail here:

  • Step 1 - Create an Enterprise Admin Account (Manual) - the business application has to register for an enteprise account. 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) - Click here for instructions
  • Step 3 - Create a Workflow Template (Manual, 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, optional) - 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 a reference in your application. Click here for more information about managing documents in an enterprise library
  • Step 5 - Get client credential token via the API (Coding) - this call authenticates the business application access to SigningHub. This requires the Enterprise Client Secret and Client Id that in return sends the access token. For authentication, the business application needs to send an HTTP POST request to SigningHub. The following is an example request/response:
Header Parameters
Content Type
required
string
Default: application/x-www-form-urlencoded
Accept
required
string
Default: application/json
REQUEST BODY SCHEMA
grant_type
required
string "client_credentials"

Define the OAuth 2.0 grant type.

client_id
required
string non-empty

Application Name that is configured in your Enterprise Account when configuring the integration options.

client_secret
required
string non-empty

API Key that that is generated in your Enterprise Account when configuring the integration options.

Post
/authenticate

Request Body

grant_type=client_credentials&

client_id= CLIENT_ID&

client_secret= CLIENT_SECRET&

Sample Response

{
access_token: "string",
token_type: "bearer",
expires_in: "0"
refresh_token: "string"
}
  • Step 6 - Register an Enterprise User via the API (Coding, Optional) - this represents the user account that will be used to upload the document and will be shared to sign the signature field. 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 developer manuals here.
Header Parameters
Content Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Authorization
required
string
Default: Bearer {access_token}

Access token obtained after a successful authentication. This service requires the access token to be obtained using the client credentials.

REQUEST BODY SCHEMA
user_email
required
string

The email address of the user account to be registered.

user_name
required
string

The name of the user to be registered.

job_title
required
string

Job title of user.

company_name
required
string

Company name of user.

mobile_number
required
string

Mobile number of user.

user_password
required
string

The password of the user account. This is optional if you want your users to authenticate externally e.g. via SAML, Salesforce, Office 365 etc. rather than using a SigningHub ID (email/password). If password is provided, application expects the security question and answer as mandatory fields.

security_question
required
string

Security question used to reset password if user forgets his password. This is mandatory if you wish to allow the user to sign without manually, via an email link, completing the registration process. If security question is provided, application expects password and security answer as mandatory fields.

security_answer
required
string

Security answer used to reset the password if user forgets his password. This is mandatory if you wish to allow the user to sign without manually, via an email link, completing the registration process. If security answer is provided, application expects password and security question as mandatory fields.

enterprise_role
required
string

The enterprise role to be assigned to this user - these are managed within the Enterprise account.

email_notification
required
string

This defines whether enterprise user would get an email notification about the account creation. Default value is 'false'.

Post
/v4/enterprise/users

Request Body

{
user_email: "john@ascertia.com",
user_name: "John Smith",
job_title: Software Engineer
company_name: Ascertia
mobile_number: 0092655675
user_password: Password@12
security_question: Favourite Book
security_answer: Harry Potter
enterprise_role: Enterprise Users
email_notification: false
}

Sample Response

{ }
  • Step 7 - Authenticate Enterprise User (Coding) - this authenticates access to SigningHub and requires the Enterprise User email address and client credentials access token. 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 to upload, prepare and share the document. Following is an example request/response:
Header Parameters
Content Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Authorization
required
string
Default: Bearer {access_token}

This service requires the access token to be obtained using the client credentials.

REQUEST BODY SCHEMA
user_email
required
string non-empty

Email of a registered enterprise user

Post
/v4/authenticate/scope

Request Body

{
user_email: "ENTERPRISE_USER_EMAIL"
}

Sample Response

{
access_token: "string",
token_type: "bearer",
expires_in: "0"
refresh_token: "string"
}
  • Step 8 - Add Package (Coding) - This service API is used to add/create a document package to hold one or more documents. This package can then be used to add documents and recipients in order to start a new workflow.
Header Parameters
Content Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Authorization
required
string
Default: Bearer {access_token_scope}

Access token returned in Scope API call

REQUEST BODY SCHEMA
package_name
required
string non-empty

The name of the package.

workflow_mode
string
Default: ONLY_OTHERS

Enum: "ME_AND_OTHERS" "ONLY_OTHERS" "ONLY_ME"

folder_name
string
Default: Inbox

The name of the folder. It will be used to upload package in any folder of the user, either its a custom folder or a shared folder.

Post
/v4/packages

Request Body

{
package_name: "string",
workflow_mode: "ME_AND_OTHERS",
folder_name: "string",
}

Sample Response

{
package_id: 1151,
workflow_mode: "ME_AND_OTHERS",
workflow_type: "string",
}
  • Step 8.1 - Add Document or dynamically add fields (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.
Path Parameters
packageId
required
integer &

The ID of the package to which the document is being added.

documentId
required
integer

The ID of the document that will be fetched from libary and added to the package

Header Parameters
Content Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Authorization
required
string
Default: Bearer {access_token_scope}

Access token returned in Scope API call

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

Post
/v4/packages/{package_id}/documents/library/{document_id}

Sample Response

{
document_id: integer,
document_name: "string",
document_order: integer
document_type: "string"
document_source: "string"
document_width: 0
document_height: 0
document_pages: 0
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
}
}
  • Step 9 - 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 is the one the user got in the response of step 8.
Path Parameters
packageId
required
integer

The ID of the package.

documentId
required
integer

The ID of the document on which the template will be applied.

Header Parameters
Content Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Authorization
required
string
Default: Bearer {access_token_user}

Access token returned in Scope API call

REQUEST BODY SCHEMA
template_name
required
string non-empty

Name of template to be applied on the document.

apply_to_all
boolen
Default: false

True, if template has to be applied on all the documents in the package.

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.

Post
/v4/packages/{packageId}/documents/{documentId}/template

Request Body

{
template_name: "string",
apply_to_all: true,
}

Sample Response

{
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
}
}
  • Step 10 - 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 optinally 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 8.
Path Parameters
packageId
required
integer

The ID of the package that has to be shared.

Header Parameters
Content Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Authorization
required
string
Default: Bearer {access_token_scope}

Access token returned in Scope API call

Post
v4/packages/{package_id}/workflow

Sample Response

[{
package_id: integer
documents: [123,124,125]
},
}]
  • Step 11 - 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.
Header Parameters
Content Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Authorization
required
string
Default: Bearer {access_token_scope}
REQUEST BODY SCHEMA
package_id
required
string non-empty

The ID of the package that has been shared in step 10.

language
string ""

Language code in which application is required be shown to end user. if no value is provided then system defined language will be used.

user_email
string ""

user_email is reqruied when a Guest user has to process the document.

callback_url
string ""

URL, where user will be redirected after completing the required actions. if no value is provided then system will follow what's been configured in Enterprise Settings > Integration

collapse_panels
boolean ""

True, will hide the panels in the iframe mode. if no value is provided then it will follow what's been set in Integration options

response_type
string ""

ENCODED, PLAIN

Post
/v4/links/integration

Request Body

{
package_id: ": "123456",
language: "en-US",
user_email: "joe@gmail.com",
callback_url: "https://web.signinghub.com/",
collapse_panels: "true",
}

Sample Response

"https://web.signinghub.com/Integration?q=QUVTMjU2LUdDTTm7sHn5UnS-2B-MB9OYT4MM4iHd4nGT-2B-3lkpLq-2B-15xg8av10bU807OEkv9fOc7jm1wsnDS1aAxCAUhEkrxup3BVNMknwQPgMGHlAAE4tdR8MbbBzbF8”
  • Step 12 - Review Document in Iframe (Coding) - Client web applications create an iframe with the source of the iframe that is being returned in step 11 as follows:

Iframe view in browser

  • 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.

    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. Response type can be encoded or plain depending on the value response_type sent in the request

Respose Details

Response Type Description
ENCODED [callback_url]?lang=en_USpackage_id%3D1017545%26action%3Dnone
Plain [callback_url]?lang=en_US&package_id=1017545&action=signed

Parameters Details

Name Description
package_id The ID of the package that was shown to the user.
action

Provides information about the action the user performed on the document. The possible values are:

  • none: There was no action
  • signed: The user signed the document
  • shared: The user shared the document
  • declined: The user declined to sign the document
  • reviewed: The user approved the document as a reviewer
  • forbidden: The user will be redirected to Call Back URL, set by the business application if a call failed due to any reason. Based on this action value, business application can take necessary action to either show message or redirect to user to any other customised screen.
  • Step 13.1 - 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)
    • a) 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.
    • b) If the client application wants to download a single document from package then use Download Document API call as explained here
The instructions above constitute a minimal but functional JSON request to SigningHub. To get in-depth details refer to the SigningHub Web Services manual.

Updates

Following are the APIs that have been affected by the changes:

Following is the list of updates in older versions

Updates in existing APIs

Document Workflow

Below are the APIs that are affected by the change.

Update Workflow User Permissions

8.3 (Update Workflow User Permissions) 8.4 (Update Workflow User Permissions)
From 8.4, SigningHub has allow to update all recipient permissions for individual workflow type
SigningHub allow to update only first recipient permissions for individual workflow type SigningHub has allow to update all recipient permissions for individual workflow type

Enterprise Management

Below are the APIs that are affected by the change.

Delete Enterprise Package

8.3 (Delete Enterprise Package) 8.4 (Delete Enterprise Package)
From 8.4, SigningHub has added the support of Client Credentials Access Token for Delete Enterprise Package
SigningHub does not have the support to Delete Enterprise Package via Client Credentials Access Token SigningHub added the support to Delete Enterprise Package via Client Credentials Access Token

SigningHub Admin APIs

Below are the APIs that are affected by the change.

Create Account

8.3 (Create Account) 8.4 (Create Account)
From 8.4, SigningHub has allow to create Individual Users
SigningHub does not have the support to Create Individual User SigningHub added the support to Create Individual User

Workflow Comments

Below are the APIs that are affected by the change.

Get Workflow Comments

8.3 (Get Workflow Comments) 8.4 (Get Workflow Comments)
From 8.4, SigningHub has introduced the private, photo_url and read parameters to provide information about comment.

Add Workflow Comments

8.3 (Add Workflow Comments) 8.4 (Add Workflow Comments)
From 8.4, SigningHub has introduced the send_to_owner and order parameter to send comments to specific users or all of them.

New parameter added

  • "send_to_owner": true

  • "order": [{1,2}]

Document Workflow

Below are the APIs that are affected by the change.

Get Workflow User Permissions

8.3 (Get Workflow User Permissions) 8.4 (Get Workflow User Permissions)
From 8.4, SigningHub has introduced the attachment parameter to provide information about required attachment.

Update Workflow User Permissions

8.3 (Update Workflow User Permissions) 8.4 (Update Workflow User Permissions)
From 8.4, SigningHub has introduced the attachment parameter to provide information about required attachment.

New parameter added

  • "attachment": {"enabled": true,"required": {"enabled": true,"note": "string"}}

Get Workflow Details

8.3 (Get Workflow Details) 8.4 (Get Workflow Details)
From 8.4, SigningHub has introduced the attachments parameter in documents model and required_attachment_added in users model to provide information about required attachment.

Get Workflow Users

8.3 (Get Workflow Users) 8.4 (Get Workflow Users)
From 8.4, SigningHub has introduced the required_attachment_added parameter to provide information about user required attachment added.

Document Preparation

Below are the APIs that are affected by the change.

Add Digital Signature Field

8.5 (Add Digital Signature Field) 8.6 (Add Digital Signature Field)
From 8.6, SigningHub has introduced the authentication_signing parameter to add Field authentication i.e OTP.

New parameters added

  • "authentication_signing": { "enabled": true, "otp": { "enabled": true, "mobile_number": "string" } }

Update Digital Signature Field

8.5 (Update Digital Signature Field) 8.6 (Update Digital Signature Field)
From 8.6, SigningHub has introduced the authentication_signing parameter to add Field authentication i.e OTP.

New parameters added

  • "authentication_signing": { "enabled": true, "otp": { "enabled": true, "mobile_number": "string" } }

Add In-person Field

8.3 (Add In-person Field) 8.4 (Add In-person Field)
From 8.4, SigningHub has introduced the level_of_assurance, and authentication_signing parameter for level of assurance assignment and Field Authentication.

For Backward Compatibility (in Database)

  • All the Allowed eSeals level of assurance are assigned and if eSeals level of assurance not allowed and electronic signature are allowed then electronic signature are assigned

New parameter added

  • "level_of_assurance": [ "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL"]

  • "authentication_signing": { "enabled": true, "otp": { "enabled": true, "mobile_number": "string" } }

Update In-person Field

8.3 (Update In-person Field) 8.4 (Update In-person Field)
From 8.4, SigningHub has introduced the level_of_assurance, and authentication_signing parameter for level of assurance assignment.

For Backward Compatibility (in Database)

  • All the Allowed eSeals level of assurance are assigned and if eSeals level of assurance not allowed and electronic signature are allowed then electronic signature are assigned

New parameter added

  • "level_of_assurance": [ "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL"]

  • "authentication_signing": { "enabled": true, "otp": { "enabled": true, "mobile_number": "string" } }

Get Document Fields

8.3 (Get Document Fields) 8.4 (Get Document Fields)
From 8.4, SigningHub has introduced the level_of_assurance in in_person_signature model for assinged level of assurances and authentication in Signature and in-person signature field authentication.

Account Management

Below are the APIs that are affected by the change.

Get User Role

8.3 (Get User Role) 8.4 (Get User Role)
From 8.4, SigningHub has introduced the in_person_level_of_assurance and in_person_default_level_of_assurance for in-person level of assurance, and enterprise_templates for to get role based templates in user_setting.

New parameters added

  • "enterprise_templates": {"Allowed": "string","Values": ["string"]}

  • "in_person_level_of_assurance": true

  • "in_person_default_level_of_assurance": true

Account Management

Below are the APIs that are affected by the change.

Get Signature Settings

8.3 (Get Signature Settings) 8.4 (Get Signature Settings)
From 8.4, SigningHub has introduced the in_person_level_of_assurance parameter in appearance for in-person default level of assurance.

Get Templates

8.3 (Get Templates) 8.4 (Get Templates)
Returned the templates From 8.4, SigningHub has updated the api logic, will return the templates based on role settings.

Document Package

Below are the APIs that are affected by the change.

Get Document Details

8.3 (Get-Document-Details) 8.4 (Get-Document-Details)
From 8.4, SigningHub has introduced the x-otp header parameter to validate document access permission via OTP authentication and x-password header parameter to validate document access permission via password authentication while accessing document.

For Backward Compatibility (in Database)

  • While Accessing The Document, if a document opening OTP permission was set by the document owner then below header parameters will be considered as required. Otherwise null or ignore

    • "x-otp": "string"

    • "x-password": "string"

New header parameters added

  • "x-otp": "string"

  • "x-password": "string"

Close Document Package

8.3 (Close Document Package) 8.4 (Close Document Package)
From 8.4, SigningHub has introduced the x-otp header parameter to validate document access permission via OTP authentication and x-password header parameter to validate document access permission via password authentication while accessing document.

For Backward Compatibility (in Database)

  • While Accessing The Document, if a document opening OTP permission was set by the document owner then below header parameters will be considered as required. Otherwise null or ignore

    • "x-otp": "string"

    • "x-password": "string"

New header parameters added

  • "x-otp": "string"

  • "x-password": "string"

Get Packages

8.5 (Get Packages) 8.6 (Get Packages)
From 8.6, SigningHub has introduced the x-recipient-details header parameter to provide recipient details regarding Document Access Duration along decline information

Document Processing

Below are the APIs that are affected by the change.

Fill Form Fields

8.3 (Fill Form Fields) 8.4 (Fill Form Fields)
From 8.4, SigningHub has introduced the x-otp header parameter to validate document access permission via OTP authentication and x-password header parameter to validate document access permission via password authentication while accessing document.

For Backward Compatibility (in Database)

  • While Accessing The Document, if a document opening OTP permission was set by the document owner then below header parameters will be considered as required. Otherwise null or ignore

    • "x-otp": "string"

    • "x-password": "string"

New header parameters added

  • "x-otp": "string"

  • "x-password": "string"

Approve Document

8.3 (Approve Document) 8.4 (Approve Document)
From 8.4, SigningHub has introduced the x-otp header parameter to validate document access permission via OTP authentication and x-password header parameter to validate document access permission via password authentication while accessing document.

For Backward Compatibility (in Database)

  • While Accessing The Document, if a document opening OTP permission was set by the document owner then below header parameters will be considered as required. Otherwise null or ignore

    • "x-otp": "string"

    • "x-password": "string"

New header parameters added

  • "x-otp": "string"

  • "x-password": "string"

Gatekeeper Approve Document

8.3 (Gatekeeper Approve Document) 8.4 (Gatekeeper Approve Document)
From 8.4, SigningHub has introduced the x-otp header parameter to validate document access permission via OTP authentication and x-password header parameter to validate document access permission via password authentication while accessing document.

For Backward Compatibility (in Database)

  • While Accessing The Document, if a document opening OTP permission was set by the document owner then below header parameters will be considered as required. Otherwise null or ignore

    • "x-otp": "string"

    • "x-password": "string"

New header parameters added

  • "x-otp": "string"

  • "x-password": "string"

Submit Document

8.3 (Submit Document) 8.4 (Submit Document)
From 8.4, SigningHub has introduced the x-otp header parameter to validate document access permission via OTP authentication and x-password header parameter to validate document access permission via password authentication while accessing document.

For Backward Compatibility (in Database)

  • While Accessing The Document, if a document opening OTP permission was set by the document owner then below header parameters will be considered as required. Otherwise null or ignore

    • "x-otp": "string"

    • "x-password": "string"

New header parameters added

  • "x-otp": "string"

  • "x-password": "string"

Bulk Sign Packages

8.3 (Bulk Sign Packages) 8.4 (Bulk Sign Packages)
From 8.4, SigningHub has introduced the transaction_id optional parameter in the request body.transaction_id is required when user need to re-initiate the signing process to complete the pending documents for which selected signing capacity does not match the level of assurance of signature fields.transaction_id will be the first transaction_id of the signing process against which re-initiation of pending documents is needed.

New header parameters added

  • "transaction_id": "string"

Authentication

SigningHub uses OAuth 2.0 to authorize client requests. The parameters required to authenticate a client application and retrieve an OAuth 2.0 access token are "grant type", "Client ID", "Client Secret", "User Name", and "Password". The "Scope" variable can be used when identifying a specific enterprise user or unregistered user (in case of electronic signatures needed from unregistered users in tight integration) as the target for operations.  Note this applies to virtually all calls except those related to digital signature operations.  

For such operations, for example in tight integration, the intended recipient credentials must be used as opposed to enterprise admin. The Authenticate API call returns an access token in the response which must be saved by the business client and must be provided with each subsequent API call as a bearer token for authorisation.  Note this token is used in tight integration scenarios for both digital and electronic signatures.

When invoking the refresh token option this will generate both a new access token for use, and refresh token for a subsequent refresh operation.  The refresh token operation means the correct grant type must be used, i.e. refresh_token, and the client_id and client_secret parameters are required.  User name, password and scope are not required.

Second Factor Authentication as OTP

If a user has OTP configured as a second factor authentication, this API will throw an error 403 with a JSON response of error and error_description. It will also send two response headers.
  • x-otp
  • x-mobile-number
x-otp will contain an access_token that will only be used to get an OTP token from OTP Login Authentication call. x-mobile-number contains phone number of the user that is found in the database. If SigningHub don't have a phone number for the user, it will be empty. 

If phone number is empty, application should ask for the phone number from the end user to send the OTP on the given number. For sending OTP, use OTP Login Authentication API call. 

Once OTP is received, client application will again call the following authenticate API to authenticate the user with two factors, i.e., Password and OTP. To submit the OTP request in the authenticate API a new request header is expected. 
  • x-otp

This request header will contain the OTP that was received on the mobile. Server side will authenticate the user based on user email, password and also verify the OTP. Once everything is verified end user will receive the access token details. 

Terms & Services

After implementation of GDPR, SigningHub will enforce the end users to agree with new terms and services, every time there is a change in it. Calling authentication API end point will check if the user has provided proper authentication information. Once validated, it will also check if the user has agreed to the latest terms and services or not. If user has already agreed to the terms everything will work in the previous fashion. If new terms and services are found that are not agreed by the user the API will send following response header as false, along with access token details. 

  • x-terms-agreed
Business application can check for this header and use the "Get Terms and Services" API end point to show the new terms and conditions to the end user for getting their consent. Once they agree, business application can call the authentication API again with the username, password and request header x-terms-agreed . Request header x-terms-agreed should have a value of true.

Note: Agreement to terms of use is required if this feature is enabled in "system settings" to meet the GDPR requirements.

Enforce Password Reset

If enterprise has set the policy to reset password on first login for newly register users or on password expiration then in that cases this API call won't return the authentication token for users. Instead, 403 with a JSON response of error and error_description would be returned. It will also send a response header.
  • x-change-password
x-change-password will contain an OneTimeAccesstoken that can only be used to set a new password for a user, by calling Set New Password  API. Once new password is set by user then  client application will again call the following authenticate API to authenticate the user successfully.


Client Credentials Authentication

Authenticate using client_id and client_secret with grant_type = client_credentials and retrieve access_token

header Parameters
Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Content-Type
string
Default: application/x-www-form-urlencoded
Request Body schema: multipart/form-data
grant_type
required
string
Default: "client_credentials"

Grant type client_credentials is used when operations are performed on behalf of the application.

client_id
required
string
Default: "ACMapAppId"

Application Name that you have configured in your Enterprise Account when configuring the integration options.

client_secret
required
string
Default: "jr67gj0h76gr83nf8734nj59g4he895jh87nr"

API Key that you generated in your Enterprise Account when configuring the integration options.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Password Authentication

Authenticate using client_id and client_secret and retrieve an OAuth 2.0 access_token

header Parameters
Accept
required
string
Default: application/json
Content-Type
string
Default: application/x-www-form-urlencoded
Request Body schema: multipart/form-data
grant_type
required
string
Default: "password"

Define the OAuth 2.0 grant type. It can be set to "password", "client_credentials", "refresh_token" or "active_directory". Note for most operations "password" is sufficient. Active Directory is used when the authentication required is the user's AD credentials. Client_credentials is reserved for internal use at this stage.

client_id
required
string
Default: "ACMEapp"

Application Name that you have configured in your Enterprise Account when configuring the integration options.

client_secret
required
string
Default: "jr67gj0h76gr83nf8734nj59g4he895jh87nr"

API Key that you generated in your Enterprise Account when configuring the integration options.

username
required
string
Default: "admin@ascertia.com"

SigningHub email address identifying the target user account - this can be an Enterprise Admin or an Enterprise User account. Note an enterprise user can use an API Key created for the enterprise by an enterprise administrator.

password
required
string
Default: "Password@12"

Password for the account defined in the 'username' parameter.

scope
string
Default: "john @ascertia.com"

Used when the Enterprise Admin user is identified in 'username' and you wish to identify an Enterprise User as the target. That is, set an enterprise user as the current user for operations. For example, to update the general profile settings of an enterprise user then the "scope" variable can be used.
If the business application directly identifies the Enterprise User and their Password for which the operations are required, i.e. in the "username" and "password" parameters, then the Scope parameter is not required.
Note all operations except for digital signature signing can be performed on behalf of an enterprise user or unregistered user using this "scope" variable.

refresh_token
string
Default: "rtfgdsxtrgefds543wedsx"

If access_token is expired, refresh token is used along with grant type refresh_token. If refresh token is provided, username, password and scope attributes can be treated as optional.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Scope Authentication

Business applications can call this API to get the scope access token on behalf of an enterprise user and perform any action other than document signing.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Scope user email address

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Kerberos Authentication

SigningHub uses OAuth 2.0 to authorize client requests. This API endpoint will present a Kerberos authentication challenge if the API is called in a browser that supports Kerberos authentication.

To get the Windows Kerberos dialog for authentication, use "withCredentials" in jQuery AJAX calls.Or on server side language like c# HttpClient object you can use "UseDefaultCredentials" with HTTP(S) requests.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

User authentication access token - bearer token for subsequent authorisation to other API calls.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
client_id
required
string non-empty

Application Name that you have configured in your Enterprise Account when configuring the integration options.

client_secret
required
string non-empty

API Key that you generated in your Enterprise Account when configuring the integration options.

profile_name
string

Responses

Request samples

Content type
{
  • "client_id": "string",
  • "client_secret": "string",
  • "profile_name": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Single Sign On Authentication

SigningHub uses OAuth 2.0 to authorize client requests. Business application can call this API to get the access token of user by requesting third party, based on provided method and token. Currently supported third parties are Office 365, Azure Active Directory, OAuth2 and OIDC.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
token
string

Token obtained from 3rd party e.g Office 365, Azure Active Directory, OAuth 2, OIDC

code
string

Code obtained from OAuth2 or OIDC (authorize response)

method
required
string non-empty

Supported method type e.g "Office_365", "Azure_Active_Directory", "OAUTH2", "OIDC"

profile_name
string

Authentication profile name, required for "OAUTH2" and "OIDC"

profile_id
required
integer <int32>

Authentication profile id, Its an alternate of profile_name

Responses

Request samples

Content type
{
  • "token": "string",
  • "code": "string",
  • "method": "string",
  • "profile_name": "string",
  • "profile_id": 0
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "authentication_access_token": "string"
}

OTP Login Authentication

SigningHub supports second factor authentication using One Time Password at login time via the web site GUI. Note this is different to OTP via SMS used in electronic signatures at the point of signing. This specifically refers to using the second factor authentication for SigningHub system access.

To enable One Time Password second factor authentication see here.It is an option in the Enterprise Role settings.

At least one SMS provider must be configured in SigningHub administration in order to use this functionality.

This API call is used to allow business applications to request an One Time Password to the user's mobile device for subsequent use in second factor authentication in the GUI.

Note the mobile number is an optional field.If not supplied, SigningHub will attempt to send the OTP to the mobile number stored in the user's Profile settings. If a mobile number is supplied in the call, then the OTP will be sent to this number, and any stored one under Profile settings will be ignored.

In the event that no mobile number is supplied, nor found under the user's Profile settings, an error will be returned.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
mobile_number
string

Mobile number of the user in case user do not have a mobile number already in his profile. SigningHub application will update the new phone number in the profile automatically.

method
string

Method Possible values are "EMAIL", "SMS"

Responses

Request samples

Content type
{
  • "mobile_number": "string",
  • "method": "string"
}

Response samples

Content type
application/json
{ }

Pre Login Authentication

Business application can use this API to get the authentication method for the user, based on the configurations set in enterprise role

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
username
required
string non-empty

Email address of the user for which authentication method is te be retrieved.

Responses

Request samples

Content type
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "profile_id": 0,
  • "profile_name": "string",
  • "method": "string",
  • "app_id": "string",
  • "tenant_id": "string",
  • "url": "string",
  • "scope": "string",
  • "resource": "string"
}

Get Service Agreements

Business applications can use this service API to get terms of services and privacy policy that are configured in SigningHub Admin console.

For details how to configure this content in SigningHub follow this link.Note the content applies across the system.

A successful response is only possible if the content is set of course.

header Parameters
Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "version_number": 0,
  • "name": "string",
  • "description": "string",
  • "terms_of_service": "string",
  • "privacy_policy": "string"
}

Get Public Authentication Profiles

Business application can use this API to get all the public authentications configured in the SigningHub.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revoke Refresh Tokens

Business application can call this API to revoke the refresh tokens generated for a user. The refresh token is generated and sent when a successful authentication request is made.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

Users access token

Accept
required
string
Default: application/json
Content-Type
string
Default: application/x-www-form-urlencoded
Request Body schema: multipart/form-data
refresh_token
required
string
Default: "45ghiukldjahdnhzdauz"

OAuth refresh access token to revoke.

token_type_hint
required
string
Default: "refresh_token"

Type of token. Currently only refresh_token is supported.

Responses

Response samples

Content type
application/json
{ }

Logout

Applications can call this API when a user logout from the application. This API call will update the user activity.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
device_token
required
string non-empty

Push notification token that needs to be removed from the server in case of logout.

Responses

Request samples

Content type
{
  • "device_token": "string"
}

Response samples

Content type
application/json
{ }

Document Package

This section entails the web services for the Document Package related operations i.e. Add, Delete, Download, and Share.

Share Document Package

Business applications can use this service API to share a document package with the signers and start a new workflow. The document should already have been prepared by 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.

path Parameters
packageId
required
integer <int32>

The document package to be shared.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Apply Workflow Template

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. When document ID is set to 0 then template will be applied to to all of the doucments in a pacakge.

While applying the template it is important to remember these two important points:

Point 1 - If the template being applied is created using a PDF which already contained form fields then ensure that the document on which this template is now being applied must contain these form fields in advance and SigningHub will NOT create those form fields via the template rather only apply the form data and assign to the respective users.

Point 2 - If the template being applied is created where form fields are manually added (hence not present in the PDF originally) via SigningHub e.g. signature field, initial, in-person signature, check boxes, radio buttons, text fields etc. then on applying such a template, these form fields will be created on the target document even if these form fields were already present in the document.

path Parameters
packageId
required
integer <int64>

The Package ID of the package to which the template needs to be applied.

documentId
required
integer <int64>

The document ID on which the template needs to be applied. If the value is set to 0, if template is to be applied on all the documents in the package.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
template_name
required
string non-empty

Name of template to be applied on the document.

apply_to_all
required
boolean

True, if template is to be applied on all the documents in the package.

Responses

Request samples

Content type
{
  • "template_name": "string",
  • "apply_to_all": true
}

Response samples

Content type
application/json
{
  • "document_id": 0,
  • "document_name": "string",
  • "document_order": 0,
  • "document_type": "string",
  • "document_width": 0,
  • "document_height": 0,
  • "document_source": "string",
  • "document_pages": 0,
  • "form_fields": true,
  • "lock_form_fields": true,
  • "uploaded_on": "string",
  • "modified_on": "string",
  • "certify": {
    },
  • "template": {
    }
}

Upload Attachment

Business applications can use this service API to upload a attachment in a document.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

ID of the document to which the attachment needs to be add.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/octet-stream
Accept
required
string
Default: application/json
x-file-name
required
string
Example: Test file.pdf

It's the name of file with extension.

x-password
string
Example: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Example: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Request Body schema: multipart/form-data
file (binary Stream)
string <binary>
Default: ""

This is the document in the raw binary format.

Responses

Response samples

Content type
application/json
{
  • "attachment_id": 0
}

Get Attachments

Business applications can use this service API to get the attachments of a document.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

ID of the document to which the attachment is added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Attachment

Business applications can use this service API to delete the attachment of a document.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

ID of the document to which the attachment is added.

attachment_id
required
integer <int32>

ID of the attachment.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Download Attachment

Business applications can use this service API to download the attachment of a document.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

ID of the document to which the attachment is added.

attachment_id
required
integer <int32>

ID of the attachment.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Download Attachment (base64)

Business applications can use this service API to download the attachment base64 of a document.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

ID of the document to which the attachment is added.

attachment_id
required
integer <int32>

ID of the attachment.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "base64": "string"
}

Add Package

This service API is used to add/create a document package to hold one or more documents. This package can then be used to add documents and recipients in order to start a new workflow.

As previously stated, this call is mandatory if you wish to work with documents. A package must exist before you can upload or add documents to SigningHub..

Even a single document is a part of a package: a package containing one document.

Note: A package can be renamed if required once created.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
package_name
string

The name of the package. Default package name is always "Untitled" if the package_name is not provided.

workflow_mode
required
string
Enum: "ME_AND_OTHERS" "ONLY_OTHERS" "ONLY_ME"
folder_name
string

The name of the folder. It will be used to upload package in any folder of the user, either it is a custom folder or a shared folder.

Responses

Request samples

Content type
{
  • "package_name": "string",
  • "workflow_mode": "ME_AND_OTHERS",
  • "folder_name": "string"
}

Response samples

Content type
application/json
{
  • "package_id": 0,
  • "workflow_mode": "string",
  • "workflow_type": "string"
}

Change Document Package Owner

Business applications can use this service API to change the owner of a document package. The new owner must be part of the same Enterprise as the current owner, and must be in an active state.

The document package must be in either In-Progress or Completed state.

The document package ID is supplied in the URL.

Only the current document owner or an Enterprise Admin can use this method.If an Enterprise Admin is using this call then the access token must be obtained using the scope parameter of the current document owner.

path Parameters
packageId
required
integer <int32>

The ID of the document package to change.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
owner
required
string non-empty

Email address of the new owner.

Responses

Request samples

Content type
{
  • "owner": "string"
}

Response samples

Content type
application/json
{ }

Close Document Package

Applications can call this API when a document package is closed by a recipient in the application. This API call will update the document reading status as well as create necessary logs.

path Parameters
packageId
required
integer <int32>

Package ID of the package which contains the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
{ }

Delete Package

Business applications can use this service API to delete a document from the user inbox. The package ID is provided in the resource URL as "{package_id}". If the document status is PENDING, then it is automatically declined as result of delete operation. If the document status is SHARED, then the document is automatically recalled and workflow is stopped before the document is deleted.

path Parameters
packageId
required
integer <int64>

Package ID of the package which contains the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Download Package

Business applications can use this service API to download the document package in binary format.

The package ID is provided in the resource URL.

If the package contains only one document, the download is the binary PDF document.

Alternatively, if the package has more than one document, the download is the binary zip file of all documents.

The x-password and x-otp headers are optional. They are required if the document owner set them during the workflow creation phase.

path Parameters
packageId
required
integer <int64>

The package ID to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
"string"

Rename Package

This service API is used to rename a document package.

The document package is identified by its unique identifier in the URL of the call.

path Parameters
packageId
required
integer <int32>

Package ID to change the name of.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
package_name
required
string non-empty

New name of the document package.

Responses

Request samples

Content type
{
  • "package_name": "string"
}

Response samples

Content type
application/json
{ }

Download Package (Base64)

Business applications can use this service API to download the document in Base64 encoded byte format.

The package ID is provided in the resource URL.

If the package contains only one document, the download is the Base64 encoded PDF document.

Alternatively, if the package has more than one document, the download is the Base64 encoded zip file of all documents.

The x-password and x-otp headers are optional. They are required if the document owner set them during the workflow creation phase.

path Parameters
packageId
required
integer <int64>

The package ID to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
"string"

Get Package Verification

Business applications can use this service API to get verification results for all the digital signature fields of all documents in a single package.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
required
string
Default: false

True if response should have images in base64 format. False will only return the resource URLs in response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Open Document Package

Applications can call this API when a document package is opened by a recipient in the application. This API call will update the document reading status as well as create necessary logs.

path Parameters
packageId
required
integer <int32>

Package ID of the package which contains the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
"string"

V4_Package_GetAllPackages

path Parameters
document_status
required
string
Enum: "ALL" "DRAFT" "INPROGRESS" "PENDING" "SIGNED" "COMPLETED" "REVIEWED" "DECLINED" "EDITED" "EXPIRING_IN_SEVEN_DAYS"
pageNo
required
integer <int32>
recordPerPage
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-folder
string
Example: SU5CT1g=

Folder name from where the documents are to be fetched. Possible values are INBOX and ARCHIVE.
Furthermore, recommended value for x-folder parameter is in Base64 encoded format.

x-search-text
string
Example: c2FsZXMgY29udHJhY3QgMTA1

Search text sent in headers for further filtration of the documents. Package id, name and document owner can be searched.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-total-records
string
Example: 212

Total number of records found with the provided search criteria.

x-source
string
Example: Library

This is the identification of the source of the document from where the document is uploaded, e.g. "My App".

x-recipient-details
string
Example: true

If "true" is passed recipient details regarding Document Access Duration will be provided along decline information

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Document

Business applications can use this service API to delete a document in a package.

path Parameters
packageId
required
integer <int32>

Package ID of the package to which the document is added.

documentId
required
integer <int32>

ID of the document to be deleted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Download Document

Business applications can use this service API to download the document bytes. The package ID and document ID is provided in the resource URL.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

The ID of the document to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
"string"

Rename Document

Business applications can use this service API to rename a document in a package.

path Parameters
packageId
required
integer <int32>

Package ID of the package to which the document is added.

documentId
required
integer <int32>

The ID of the document to on which the action is to be performed.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
document_name
required
string non-empty

New name of the document.

Responses

Request samples

Content type
{
  • "document_name": "string"
}

Response samples

Content type
application/json
{ }

Upload XML StyleSheet (.XSLT)

Business applications can use this service API to upload an XSLT StyleSheet to transform an XML document into HTML formatted PDF document on SigningHub viewer. This API is support client credential scope too to upload XSLT StyleSheet and it will restrict to upload XSLT StyleSheet if document is signed and target document is not XML

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the XML document is belonged.

documentId
required
integer <int64>

Document ID of the XML document that need to formatted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Accept
required
string
Default: application/json
Content-Type
string
Default: application/octet-stream
x-file-name
string
Default: Test file.pdf

It's the name of file with extension.

Request Body schema: multipart/form-data
file (binary Stream)
string <binary>
Default: ""

This is the document in the raw binary format.

Responses

Response samples

Content type
application/json
{
  • "documentid": 0
}

Download Document (Base64)

Business applications can use this service API to download the document in base64 string format. The package and document ID is provided in the resource URL.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

The ID of the document to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
"string"

Upload XML StyleSheet (.XSLT) Base64

Business applications can use this service API to upload an XSLT StyleSheet (base64) to transform an XML document into HTML formatted PDF document on SigningHub viewer. This API is support client credential scope too to upload XSLT StyleSheet (base64) and it will restrict to upload XSLT StyleSheet if document is signed and target document is not XML

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the XML document is belonged.

documentId
required
integer <int64>

Document ID of the XML document that need to formatted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Accept
required
string
Default: application/json
Content-Type
string
Default: application/octet-stream
x-file-name
string
Default: Test file.pdf

It's the name of file with extension.

x-base64
required
string
Default: true

True mean uploaded document is in base64 format.

Request Body schema:
document
required
string non-empty

Base64 converted string of XML Beautifier file (.XSLT) need to upload

Responses

Request samples

Content type
{
  • "document": "string"
}

Response samples

Content type
application/json
{
  • "documentid": 0
}

Upload Document Base64

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is being added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Accept
required
string
Default: application/json
Content-Type
string
Default: application/octet-stream
x-file-name
string
Default: Test file.pdf

It's the name of file with extension.

x-convert-document
string
Default: true

This identifies whether to convert the document to a PDF or if it should be retained in its original format. Note the only original format supported is currently Word & XML. All other document types will result in an error if this header value is set to "false". If uploading a PDF document this Header can be omitted.

x-source
string
Default: API

This is the identification of the source of the document from where the document is uploaded, e.g. "My App".

x-base64
required
string
Default: true

True mean uploaded document is in base64 format.

Request Body schema:
document
required
string non-empty

Base64 converted string of document need to upload

Responses

Request samples

Content type
{
  • "document": "string"
}

Response samples

Content type
application/json
{
  • "documentid": 0
}

Add Document from Library

Business applications can use this service API to add a document from the user’s library to a package. Package ID is provided in the URL, the ID of the document should also be provided as “document_id” in the resource URL to identify the library document to be copied.

Note a package must already exist before you can add a document using this call.

path Parameters
packageId
required
integer <int64>

The Package ID of the package to which the document is being added.

documentId
required
integer <int64>

The document ID for which the document details are requested.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "document_id": 0,
  • "document_name": "string",
  • "document_order": 0,
  • "document_type": "string",
  • "document_source": "string",
  • "document_width": 0,
  • "document_height": 0,
  • "document_pages": 0,
  • "uploaded_on": "2019-08-24T14:15:22Z",
  • "modified_on": "2019-08-24T14:15:22Z",
  • "form_fields": true,
  • "lock_form_fields": true,
  • "certify": {
    },
  • "template": {
    }
}

Upload Document

Business applications can use this service API to add a document to a document package linked to an enterprise user’s account. The document information is sent in the HTTP request header and document bytes are sent in the HTTP request body. Note SigningHub will convert supported document formats to PDF if the header "x-convert-document" is set to a value of "true". The only case supported where this value is set to "false" is to retain Word format and XML documents.

SigningHub supports a wide variety of document formats, each of which can be converted to PDF format upon upload.Click here for the full list.

Note PDF documents are not altered upon upload to the system.

Note a package must already exist before you can add a document using this call.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is being added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Accept
required
string
Default: application/json
Content-Type
string
Default: application/octet-stream
x-file-name
string
Default: Test file.pdf

It's the name of file with extension.

x-convert-document
string
Default: true

This identifies whether to convert the document to a PDF or if it should be retained in its original format. Note the only original format supported is currently Word & XML. All other document types will result in an error if this header value is set to "false". If uploading a PDF document this Header can be omitted.

x-source
string
Default: API

This is the identification of the source of the document from where the document is uploaded, e.g. "My App".

Request Body schema: multipart/form-data
file (binary Stream)
string <binary>
Default: ""

This is the document in the raw binary format.

Responses

Response samples

Content type
application/json
{
  • "documentid": 0
}

Get Certify Policy for a document

Business applications can use this service API to get certify signature settings of a document in a package.

path Parameters
packageId
required
integer <int32>

Package ID of the package to which the document is added.

documentId
required
integer <int32>

The ID of the document to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "certify": {
    },
  • "lock_form_fields": true
}

Update Certify Policy for a document

Business applications can use this service API to update certify signature settings for a document in a package.

path Parameters
packageId
required
integer <int32>

Package ID of the package to which the document is added.

documentId
required
integer <int32>

The ID of the document on which the action is to be performed.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
object

Certify settings object for the document.

lock_form_fields
required
boolean

True if form fields are to be locked after the last signature on the current document.

Responses

Request samples

Content type
{
  • "certify": {
    },
  • "lock_form_fields": true
}

Response samples

Content type
application/json
{ }

Get Document Details

Business applications can use this service API to get the document details. The document ID is provided in the URL as “{document_id}”.

path Parameters
packageId
required
integer <int64>

The Package ID of the package to which the document is added.

documentId
required
integer <int64>

The document ID for which the document details are requested.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
{
  • "document_id": 0,
  • "document_name": "string",
  • "document_order": 0,
  • "document_type": "string",
  • "document_width": 0,
  • "document_height": 0,
  • "document_source": "string",
  • "document_pages": 0,
  • "form_fields": true,
  • "lock_form_fields": true,
  • "uploaded_on": "string",
  • "modified_on": "string",
  • "certify": {
    },
  • "template": {
    }
}

Get Document Image

Business applications can use this service API to get verification results for all the digital signature fields of all documents in a single package.

path Parameters
packageId
required
integer <int64>

Package ID of the package of which the document is part of.

documentId
required
integer <int64>

The ID of the document for which the image is to be requested.

pageNo
required
integer <int32>

Page number in the document for which the image is requested.

widthHeight
required
string

Dimensions are provided in the URL in the form of width x height. This width height can be any value desired by the client application. Width and height are calculated in pixels.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

x-page-width
string
Default: 600

Width of the image returned in response.

x-page-height
string
Default: 800

Height of the image returned in response.

Responses

Response samples

Content type
application/json
"string"

Get Document Image (Base64)

Business applications can use this service API to get an image of a particular page as identified by the page_no. 800 x 600 can be replaced by any given resolution to match the device displaying resolution.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document belongs.

documentId
required
integer <int64>

The ID of the document for which the image is to be requested.

pageNo
required
integer <int32>

Page number in the document for which the image is requested.

widthHeight
required
string

Dimensions are provided in the URL in the form of width x height. This width height can be any value desired by the client application. Width and height are calculated in pixels.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

x-page-width
string
Default: 600

Width of the image returned in response.

x-page-height
string
Default: 800

Height of the image returned in response.

Responses

Response samples

Content type
application/json
"string"

Get Document Verification

Business applications can use this service API to get verification results for all the digital signature fields of a document in a package.

path Parameters
packageId
required
integer <int64>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

The ID of the document to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
required
string
Default: true

True if response should have images in base64 format. False will only return the resource URLs in response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Change Document Order

Business applications can use this service API to change the order of a document in a package.

path Parameters
packageId
required
integer <int32>

Package ID of the package to which the document is added.

documentId
required
integer <int64>

The ID of the document to on which the action is to be performed.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

New order of the document in the package.

Responses

Request samples

Content type
{
  • "order": 0
}

Response samples

Content type
application/json
{ }

Document Workflow

This section entails the web services for the Document Workflow related operations i.e. Get Details, Add/Update Users, and Permissions.

Get Workflow User Permissions of Enterprise Package

Business applications can use this service API to get document permissions for a recipient. Recipient is identified by the order in the workflow. The ID of the package is provided in the resource URL.

path Parameters
packageId
required
integer <int64>

The document ID for which workflow user needs to be updated.

order
required
integer <int32>

The order of the user in workflow for which the permissions are requested. By providing the value 0 in order, service would return the permissions of most recently added collaborator in the workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "print": true,
  • "download": true,
  • "add_text": true,
  • "change_recipients": true,
  • "add_attachment": true,
  • "attachment": {
    }
}

Update Workflow User Permissions of Enterprise Package

Business applications can use this service API to update the workflow permissions for a user that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications want to override the permissions within the workflow. The ID of the document package is provided in the resource URL, and the workflow user is identified by the order at which it is added to the workflow.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow permissions to be updated.

order
required
integer <int32>

The order of the recipient for which the workflow permissions to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:

Business applications can use this service API to update the workflow permissions for a user that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications want to override the permissions within the workflow. The ID of the document package is provided in the resource URL, and the workflow user is identified by the order at which it is added to the workflow.

apply_to_all
required
boolean

True, if the permissions are to be applied on all the recipients in the workflow.

required
object

It has all the permissions to be allowed in the workflow

Responses

Request samples

Content type
{
  • "apply_to_all": true,
  • "permissions": {
    }
}

Response samples

Content type
application/json
{ }

Get Workflow User Authentication (Document Opening) of Enterprise Package

Business applications can use this service API to get the access security settings enabled for the package. Recipients for whom the security is configured are identified by the order in the URL. Package ID is also identified in the request URL. Recipients will not be able to access document package outside the scope of this duration if the access security is enabled. Document owner can also configure authentication based security of the package for a recipient.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow access security and authentication is to be updated.

order
required
integer <int32>

Order of the recipient in the workflow for which the access security and authentication is to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "authentication": {
    },
  • "authentication_signing": {
    },
  • "access_duration": {
    }
}

Update Workflow User Authentication (Document Opening) of Enterprise Package

Business applications can use this service API to update the package authentications and access duration for the recipients.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow access security and authentication is to be updated.

order
required
integer <int32>

Order of the recipient in the workflow for which the access security and authentication is to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
apply_to_all
required
boolean

True, if the access security or authentications are to be applied on all the recipients in the workflow.

required
object

It has the access aauthentication data

object

It has the signing authentication data

required
object

It has the access duration of the workflow

Responses

Request samples

Content type
{
  • "apply_to_all": true,
  • "authentication": {
    },
  • "authentication_signing": {
    },
  • "access_duration": {
    }
}

Response samples

Content type
application/json
{ }

Get Workflow User Permissions

Business applications can use this service API to get document permissions for a recipient. Recipient is identified by the order in the workflow. The ID of the package is provided in the resource URL.

path Parameters
packageId
required
integer <int64>

The document ID for which workflow user needs to be updated.

order
required
integer <int32>

The order of the user in workflow for which the permissions are requested. By providing the value 0 in order, service would return the permissions of most recently added collaborator in the workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "print": true,
  • "download": true,
  • "add_text": true,
  • "change_recipients": true,
  • "add_attachment": true,
  • "legal_notice": {
    },
  • "attachment": {
    }
}

Update Workflow User Permissions

Business applications can use this service API to update the workflow permissions for a user that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications want to override the permissions within the workflow. The ID of the document package is provided in the resource URL, and the workflow user is identified by the order at which it is added to the workflow.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow permissions to be updated.

order
required
integer <int32>

The order of the recipient for which the workflow permissions to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:

Business applications can use this service API to update the workflow permissions for a user that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications want to override the permissions within the workflow. The ID of the document package is provided in the resource URL, and the workflow user is identified by the order at which it is added to the workflow.

apply_to_all
required
boolean

True, if the permissions are to be applied on all the recipients in the workflow.

required
object

It has all the permissions to be allowed in the workflow

Responses

Request samples

Content type
{
  • "apply_to_all": true,
  • "permissions": {
    }
}

Response samples

Content type
application/json
{ }

Get Workflow User Authentication (Document Opening)

Business applications can use this service API to get the access security settings enabled for the package. Recipients for whom the security is configured are identified by the order in the URL. Package ID is also identified in the request URL. Recipients will not be able to access document package outside the scope of this duration if the access security is enabled. Document owner can also configure authentication based security of the package for a recipient.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow access security and authentication is to be updated.

order
required
integer <int32>

Order of the recipient in the workflow for which the access security and authentication is to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "authentication": {
    },
  • "authentication_signing": {
    },
  • "access_duration": {
    }
}

Update Workflow User Authentication (Document Opening)

Business applications can use this service API to update the package authentications and access duration for the recipients.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow access security and authentication is to be updated.

order
required
integer <int32>

Order of the recipient in the workflow for which the access security and authentication is to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
apply_to_all
required
boolean

True, if the access security or authentications are to be applied on all the recipients in the workflow.

required
object

It has the access aauthentication data

object

It has the signing authentication data

required
object

It has the access duration of the workflow

Responses

Request samples

Content type
{
  • "apply_to_all": true,
  • "authentication": {
    },
  • "authentication_signing": {
    },
  • "access_duration": {
    }
}

Response samples

Content type
application/json
{ }

Update Workflow Details

Business applications can use this service API to update the workflow details. Normally this call is useful after a template has been applied to a document, but business applications wants to override the certify permission or post processing details. The package ID is provided in the resource URL.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow details need to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
workflow_type
string
Enum: "SERIAL" "INDIVIDUAL" "PARALLEL" "CUSTOM"
workflow_mode
string
Enum: "ME_AND_OTHERS" "ONLY_OTHERS" "ONLY_ME"
continue_on_decline
boolean

True, if workflow needs to continue even if any recipient declines the document. If no value is provided, old value will be retained.

message
string

A custom string message from the document owner to every recipient, this message appears in the sharing email as well as on the screen. If no value is provided, old value will be retained.

Responses

Request samples

Content type
{
  • "workflow_type": "SERIAL",
  • "workflow_mode": "ME_AND_OTHERS",
  • "continue_on_decline": true,
  • "message": "string"
}

Response samples

Content type
application/json
{ }

Get Workflow Details

Business applications can use this service API to get workflow details for the package.

path Parameters
packageId
required
integer <int64>

The ID of the package to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "package_id": 0,
  • "package_name": "string",
  • "package_owner": "string",
  • "owner_name": "string",
  • "package_status": "string",
  • "folder": "string",
  • "gatekeeper": true,
  • "next_signer": "string",
  • "next_signer_email": [
    ],
  • "uploaded_on": "string",
  • "modified_on": "string",
  • "workflow": {
    },
  • "documents": [
    ],
  • "users": [
    ]
}

Update Post Processing

Business applications can use this service API to add placeholder to a workflow a document in a package.

path Parameters
packageId
required
integer <int64>

ID of the document package for which the post processing is being updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
enabled
required
boolean

True, if post processing is turned on for the package.

contacts
Array of strings
Array of objects (PostProcessRecipientRequest)

List of the name and email addresses to whom the emails are sent when the post processing is executed after the workflow completion.

message
string

A custom string message for all the contacts. Message becomes part of the email sent to the contacts.

google_drive
boolean

True, if document is to be uploaded to the provided google account after the workflow completion.

dropbox
boolean

True, if document is to be uploaded to the provided dropbox account after the workflow completion.

workflow_recipients
required
boolean

True, if workflow completion report is to be sent to all recipients of the workflow when post processing is executed. Default value is false.

Responses

Request samples

Content type
{
  • "enabled": true,
  • "contacts": [
    ],
  • "recipients": [
    ],
  • "message": "string",
  • "google_drive": true,
  • "dropbox": true,
  • "workflow_recipients": true
}

Response samples

Content type
application/json
{ }

Add Users to Workflow

Business applications can use this service API to add recipients to a workflow. This call will only add a recipient to the workflow. That is, no fields currently on the document will be automatically assigned to the new recipient(s), nor will this create any new fields.

Note the recipient(s) will be added as the last person in the workflow.Hence further work may be required to remove a current recipient(s) already present in the workflow.

At least one user must exist in a workflow before fields (input and signature) can be added to the document.

Note the input accepts one or more users in a single call.

In this specific call the user is a known natural person. However, the same rules apply to Groups and Placeholders. In either of these cases the recipient becomes a Group of users whereby any member of the group can sign the document, or a Placeholder.The latter case is used when you do not know the identity of the intended signatory.

Note SigningHub workflow signing order starts at "1". Hence, adding a user to workflow with no current recipient(s) begins a new signing order count.The "signing_order" parameter is mandatory if the workflow type is "custom".

Important, using this API call may affect the workflow type.If there are current recipients in a sequential workflow and a new one is added with the same signing order as a current recipient, then that part of the workflow changes automatically from sequential to parallel.Hence, the workflow overall is now of type custom as opposed to purely sequential. Adding a recipient with the same signing order as two or parallel recipients does not change the workflow.There are merely, three or more recipients at that particular point of the workflow; all in parallel order.

Note, while XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"

path Parameters
packageId
required
integer <int64>

SigningHub package ID, which the recipients are to be added to.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Array
user_email
required
string non-empty

Email address of the user to be added in the workflow.

user_name
required
string non-empty

Name of the recipient to be added in the workflow.

email_notification
required
boolean

If set as true, SigningHub will send notifications to the user via email as per the document owner and user notification settings. A value of false means no notifications will be sent to user throughout the workflow.

role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order of the recipient in the workflow. This signing order is mandatory when workflow type is "CUSTOM".

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Get Workflow Users

Business applications can use this service API to get workflow details for the package.

path Parameters
packageId
required
integer <int64>

The ID of the package to be downloaded.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Groups to Workflow

Business applications can use this service API to add groups as a recipient to a workflow. A SigningHub group means any member of the group can perform the action, i.e. sign, on behalf of all members of the group.

Note the group will be added as the last user/group in the workflow.Hence further work may be required to remove a current user/group, already present in the workflow. While XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"

path Parameters
packageId
required
integer <int64>

ID of the package for which the group is to be added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Array
group_name
string

The name of the new group to be added in workflow.

email_notification
required
boolean

Setting its value to "true" sends an email notification to the user when its turn arrives in workflow. Setting its value to "false" does not send the email notification to the user on its turn. If no value is provided, default value of "true" will be set.

role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
application/json
{ }

Add Placeholder to Workflow

Business applications can use this service API to add placeholder to a workflow in a package. A place holder is required when you do not know the identity of the intended recipient in a workflow.

Note the placeholder will be added as the last user in the workflow.Hence further work may be required to remove a current user/group, already present in the workflow.

Adding a place holder allows you to proceed and add signature and/or input fields to the document, which can then be assigned to individual users at a later stage. While XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"

path Parameters
packageId
required
integer <int64>

ID of the package for which the placeholder is to be added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Array
placeholder
string

The name of the new placeholder to be added in workflow.

email_notification
required
boolean

Setting its value to "true" sends an email notification to the user when its turn arrives in workflow. Setting its value to "false" does not send the email notification to the user on its turn.

role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
application/json
{ }

Update Placeholder

Business applications can use this service API to update a placeholder in the workflow. Normally this call is useful after a template has been applied to a document and business applications wants to override the details of a specific place holder within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow place holder is identified by the order at which it is added to the workflow. While XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"

path Parameters
packageId
required
integer <int64>

ID of the package for which the placeholder is to be added.

order
required
integer <int32>

Order of the recipient in the workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
placeholder
string

The name of the new placeholder to be added in workflow. If no value is provided, old value will be retained.

email_notification
boolean

Setting its value to "true" sends an email notification to the user when its turn arrives in workflow. Setting its value to "false" does not send the email notification to the user on its turn. If no value is provided, old value will be retained.

role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

Responses

Request samples

Content type
{
  • "placeholder": "string",
  • "email_notification": true,
  • "role": "SIGNER",
  • "signing_order": 0
}

Response samples

Content type
application/json
{ }

Update Workflow User

Business applications can use this service API to update the details of a recipient, group or place holder who has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications wants to override the details of a specific user within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow recipient is identified by the order at which it is added to the workflow. Note, while XML type document preparation, only supports role types "SIGNER", "REVIEWER" and "CARBON_COPY".

path Parameters
packageId
required
integer <int64>

The package ID for which workflow user needs to be updated.

order
required
integer <int32>

The order of the user in workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

The email address of the new user to be updated in workflow. If no value is provided, old value will be retained.

user_name
string

Name of the recipient to be updated. If no value is provided, old value will be retained.

email_notification
boolean

Setting its value to "true" sends an email notification to the user when its turn arrives in workflow. Setting its value to "false" does not send the email notification to the user on its turn. If no value is provided, old value will be retained.

mobile_number
string
role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

email_language_code
string

email language code

Responses

Request samples

Content type
{
  • "user_email": "string",
  • "user_name": "string",
  • "email_notification": true,
  • "mobile_number": "string",
  • "role": "SIGNER",
  • "signing_order": 0,
  • "email_language_code": "string"
}

Response samples

Content type
application/json
{
  • "user_email": "string",
  • "signing_order": 0,
  • "guest_user": true,
  • "email_language_code": "string"
}

Update Workflow Users Order

Business applications can use this service API to update order of the recipient in the workflow.

path Parameters
packageId
required
integer <int64>

ID of the package to which the recipients are to be added.

order
required
integer <int32>

Existing order of the recipient which is to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

Existing order of the recipient which is to be updated.

Responses

Request samples

Content type
{
  • "order": 0
}

Response samples

Content type
application/json
{ }

Update Workflow Group

Business applications can use this service API to update the details of a group that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications wants to override the details of a specific group within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow group is identified by the order at which it is added to the workflow. While XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"

path Parameters
packageId
required
integer <int64>

The package ID for which workflow group needs to be updated.

order
required
integer <int32>

The order of the user in workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
group_name
string

The name of the group to be updated in workflow. If no value is provided, old value will be retained.

email_notification
boolean

Setting its value to "true" sends an email notification to the group members when their turn arrives in workflow. Setting its value to "false" does not send the email notification to the group members on their turn. If no value is provided, old value will be retained.

access_sms_otp
boolean
mobile_number
string
role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

Responses

Request samples

Content type
{
  • "group_name": "string",
  • "email_notification": true,
  • "access_sms_otp": true,
  • "mobile_number": "string",
  • "role": "SIGNER",
  • "signing_order": 0
}

Response samples

Content type
application/json
{ }

Delete Workflow User

Business applications can use this service API to delete workflow recipient.

path Parameters
packageId
required
integer <int64>

The package ID from which the recipient is to be deleted.

order
required
integer <int32>

Order of the recipient in the workflow which is to be deleted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Update Workflow Reminders

Business applications can use this service API to update the workflow reminders for a recipient that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications want to override the reminders settings within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow recipient is identified by the order at which it is added to the workflow.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow reminders to be updated.

order
required
integer <int32>

The order of the user for which the workflow reminders to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
apply_to_all
required
boolean

True, if reminder settings are to be applied on all the recipients in the workflow.

enabled
required
boolean

True, if reminder settings are to be enabled.

remind_after
required
integer <int32>

Required, in case of enabled property will true. The number of days after which the first reminder would be sent to workflow user.

object

The reminders would be sent to user repeatedly.

Responses

Request samples

Content type
{
  • "apply_to_all": true,
  • "enabled": true,
  • "remind_after": 0,
  • "repeat": {
    }
}

Response samples

Content type
application/json
{ }

Get Workflow Reminder

Business applications can use this service API to update the reminders for the recipients that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications want to override the reminders settings within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow recipient is identified by the order at which it is added to the workflow.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow reminders to be updated.

order
required
integer <int32>

The order of the user for which the workflow reminders to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "remind_after": 0,
  • "repeat": {
    }
}

Get Workflow History

Business applications can use this service API to get the list of actions performed on the document. The package ID is provided in the resource URL.

path Parameters
packageId
required
integer <int64>

The ID of the document for which log is required.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "package_id": 0,
  • "package_name": "string",
  • "package_owner": "string",
  • "owner_name": "string",
  • "package_status": "string",
  • "next_signer": "string",
  • "next_signer_email": [
    ],
  • "documents": [
    ],
  • "actions": [
    ]
}

Get Workflow History Details

Business applications can use this service API to get the details of an action performed in the document. The action is identified by the log_id provided in the resource URL. The package ID is provided in the resource URL.

path Parameters
packageId
required
integer <int64>

The ID of the package for which log is required.

logId
required
integer <int64>

The ID of the log action for which the details are requested.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
string
Default: true

True if response should have images in base64 format. False will only return the resource URLs in response.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "key": "string",
  • "value": "string",
  • "visible": true,
  • "order": 0,
  • "certificate_base64": "string",
  • "certificate_base64_url": "string",
  • "type": "string"
}

Get Certificate Saved In Workflow History

Business application can get the certificate that was used for to perform an workflow activity. Business application will need to provide the package id, log id and the key by which the certificate is retrieved. This API endpoint will be returned in activity log response. Client application will not need to create the whole URL on its own.

path Parameters
packageId
required
integer <int64>

Id of the package for which the activity log was retrieved.

logId
required
integer <int64>

Id of the activity log record.

encryptKey
required
string

A key attribute that identifies the certificate with this activity. Key is encrypted by application so end user do not need to know the keys. Mostly this API URL will be returned in the activity log response.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Complete Workflow in the Middle (Terminate Workflow)

Business applications can mark the workflow completed even in the middle of the workflow. Use this service API to change the status of the workflow to completed. If there are recipients who have not signed the document yet. Their signature will not be required any more and they will not be able to see the document in their inbox any further. Bearer token should belong to document owner or enterprise admin can use scope variable to get the access token on behalf of document owner to perform this action.

path Parameters
packageId
required
integer <int64>

The package ID from which the recipient is to be deleted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Add Workflow Comments

Business applications can add the comments in the workflow. Use this service API to add comments in workflow. Bearer token should belong to document owner or enterprise admin can use scope variable to get the access token on behalf of document owner to perform this action.

path Parameters
packageId
required
integer <int64>

The package ID in which comments need to be added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
send_to_owner
required
boolean

If document owner is included in everyone's drop down but not a part of workflow collaborators

order
Array of integers <int32> [ items <int32 > ]

If user wanna send comments to multiple recipients

text
required
string non-empty

Workflow Comment text

Responses

Request samples

Content type
{
  • "send_to_owner": true,
  • "order": [
    ],
  • "text": "string"
}

Response samples

Content type
application/json
{ }

Get Workflow Comments

Business applications can get the comments in the workflow. Use this service API to get comments in workflow. Bearer token should belong to document owner or enterprise admin can use scope variable to get the access token on behalf of document owner to perform this action.

path Parameters
packageId
required
integer <int64>

The package ID to get the workflow comments.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-order
string

When signing order is passed then only selected signing order comments list will be returned.

x-private
string

When set as "true" only private comments list will be returned. In case of "false" only public comments list will be returned.If you do not set the header, then both private and public comments lists will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark as Read Workflow Comments

Business applications can mark as read comments in the workflow. Use this service API to mark as read comments in workflow. Bearer token should belong to document owner or enterprise admin can use scope variable to get the access token on behalf of document owner to perform this action.

path Parameters
packageId
required
integer <int64>

The package ID in which comments need to be mark as read.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-mark-as-read
string

When set as "true" then comments are maked as read

Responses

Response samples

Content type
application/json
{ }

Get Process Evidence Report

Business applications can use this service API to download the workflow process evidence report of a document.

path Parameters
packageId
required
integer <int64>

The ID of the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Open Document via Password

Business applications can use this service API to submit a password from a particular recipient, specified by the order.

path Parameters
packageId
required
integer <int64>

The ID of the package for which the password is submitted.

order
required
integer <int32>

The order of the user for which the password is to be submitted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
password
required
string non-empty

String password for the document package for verification and opening the package.

Responses

Request samples

Content type
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

Open Document via OTP (Generate)

Business applications can use this service API to generate an OTP for a particular recipient, specified by the order.

path Parameters
packageId
required
integer <int64>

The ID of the package for which the OTP is to be generated.

order
required
integer <int32>

The order of the recipient for which the OTP is to be generated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:

The OTP method.

method
string

Method Possible values are "EMAIL", "SMS"

Responses

Request samples

Content type
{
  • "method": "string"
}

Response samples

Content type
application/json
{ }

Add Shared Space

Business applications can use this service API to create shared space. The availability of creating shared spaces is subject to the assigned enterprise user role. To allow this provision Enterprise Admin will enable the ‘Manage Shared Space’ option in Roles>Document Settings.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
name
string

Name of shared space

Array of objects (WorkSpaceMembers)

Members of shared space

Responses

Request samples

Content type
{
  • "name": "string",
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0
}

Get Shared Spaces

Business applications can use this service API to get all the shared space belonging to the user. This API returns information about shared spaces, its owner and collaborators.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: c2FsZXMgY29udHJhY3QgMTA1

Search text sent in headers for further filtration of the documents. Shared space id, name and shared space owner can be searched.
Furthermore, recommended value for search text parameter is in Base64 encoded format, however plain English text can also be provided

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Shared Space

Business applications can use this service API to delete shared space. The availability of deleting shared spaces is subject to the assigned enterprise user role. To allow this provision Enterprise Admin will enable the ‘Manage Shared Space’ option in Roles>Document Settings.

path Parameters
id
required
integer <int64>

Id of shared space that you want to delete

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Get Shared Space

Business applications can use this service API to get a specific shared space. This API returns information about shared space, its owner and collaborator.

path Parameters
id
required
integer <int64>

Id of shared space that you want to get

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "owner": {
    },
  • "members": [
    ]
}

Update Shared Space

Business applications can use this service API to update shared space. The availability of updating shared spaces is subject to the assigned enterprise user role. To allow this provision Enterprise Admin will enable the ‘Manage Shared Space’ option in Roles>Document Settings.

path Parameters
id
required
integer <int64>

Id of shared space that you want to update

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
name
string

Name of shared space

Array of objects (WorkSpaceMembers)

Members of shared space

Responses

Request samples

Content type
{
  • "name": "string",
  • "members": [
    ]
}

Response samples

Content type
application/json
{ }

Get Shared Space documents

Business applications can use this service API to get documents in a specific shared space. The document package details are fetched through this call.

path Parameters
id
required
integer <int64>

Id of shared space for which you wanna to get document list

document_status
required
string
Enum: "ALL" "DRAFT" "INPROGRESS" "PENDING" "SIGNED" "COMPLETED" "REVIEWED" "DECLINED" "POSTPROCESS" "RECALLED" "ESIGNED" "PUBLISHDOCUMENTHISTORY" "REMINDER" "EDITED" "ARCHIVED" "EXPIRING_IN_SEVEN_DAYS" "ADD_COMMENT"

Filter by document status possible values are ALL, DRAFT, PENDING, SIGNED, DECLINED, INPROGRESS, COMPLETED.

pageNo
required
integer <int32>

Page number, according the division of records per page.

recordPerPage
required
integer <int32>

Number of records that are needed to be fetched in one request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: c2FsZXMgY29udHJhY3QgMTA1

Search text sent in headers for further filtration of the documents. Package id, name and document owner can be searched.
Furthermore, recommended value for search text parameter is in Base64 encoded format, however plain English text can also be provided

x-total-records
string
Example: 212

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Move Package to Custom/Shared Space folder

Business applications can use this service API to move the document package to a shared space or user's custom folder.

path Parameters
packageId
required
integer <int64>

Package id that need to move to folder

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:

Target folder name

folder_name
string

Target folder name in which package need to move

Responses

Request samples

Content type
{
  • "folder_name": "string"
}

Response samples

Content type
application/json
{ }

Document Preparation

This section entails the web services for the Document Preparation i.e. Add/Update/Delete Fields.

Assign Document Field

Business applications can use this service API to assign users to input fields, e.g. signature fields, and hence define the signing order. The fields must already be present in the document and the users must be present in the workflow. The ID of the workflow document is provided in the resource URL, along with the package identifier.

When recipients are in a workflow they are numbered, beginning at one and counting up for each extra one.Therefore, if there are three users in a workflow they are numbered "1", "2", and "3" respectfully.This API call allows you to assign a user by their workflow order number, to an input field on the document.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which workflow user needs to be updated.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Array
field_name
required
string non-empty

Name of the signature field that is to be assigned.

radio_group_name
string

provide group name for radio box

order
required
integer <int32>

The order of the user in workflow, to which the field is being assigned.

level_of_assurance
Array of strings

Level Of Assurance to be added. Possible Values are "ELECTRONIC_SIGNATURE", "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SIGNATURE", "HIGH_TRUST_ADVANCED", "QUALIFIED_ELECTRONIC_SIGNATURE"

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
application/json
{ }

AutoPlace Fields

Business applications can call this API to add signature or user defined form fields to a document based upon the search criterion supplied. The placement options are: to the left, to the right, top and bottom. The document is search and all instances of the search criteria met are processed. This allows you to add multiple fields with one call. For example, upload a document and automatically place a signature field to the right of all instances of the word "Sign here:". This saves time and ensures no signatures are missed from the workflow.

The API call supports all types of fields; namely electronic, digital, in-person, initials, and text field etc.

In addition, the API call supports the "order" variable.This means you can assign a set of signature fields automatically to a single user.Hence, the call can be repeated to place and assign signature fields to more than one user in the workflow.

At least one user must exist in a workflow before signature fields can be added to the document in this way.The order number corresponds to the recipient in the workflow. Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

This API call can be used multiple times on the same document.The reason for doing so is to cater for multiple signatories on a document.The recipient or signatory is identified by the "order" variable passed in the call.

See Add Users to Workflow for more information. Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

path Parameters
packageId
required
integer <int64>

The ID of the package to which the document is added.

documentId
required
integer <int64>

The ID of the document for which the fields are requested.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
search_text
string

Word that needs to be searched in the document.

order
required
integer <int32>

Order of the user to which the fields will be assigned automatically. Workflow in SigningHub orders recipients. This list begins with “1” for the first designated signer.

placement
string

If the text is found, fields are to be placed in the document. Placement of the field can be mentioned in this attribute. Possible values of placement of a field are LEFT, RIGHT, TOP, BOTTOM. If no value is provided the default value will be LEFT.

field_type
string

Type of field to be created in the document. Possible values are "SIGNATURE", "IN_PERSON_SIGNATURE", "INITIALS", "TEXT", "NUMBER" ,"NAME", "EMAIL", "COMPANY", "JOBTITLE", "RADIOBOX", "CHECKBOX", "DATE"

level_of_assurance
Array of strings

Level Of Assurance to be updated. Possible Values are "ELECTRONIC_SIGNATURE", "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SIGNATURE", "HIGH_TRUST_ADVANCED", "QUALIFIED_ELECTRONIC_SIGNATURE"

object

Dimensions of a field to be created in the document. X and Y location is calculated automatically. API can only configure width and height for the field. If dimensions are not provided default dimensions will be followed. that is 200 x 80 in pixels.

placeholder
string
radio_group_name
string

The group name required only when adding a Radio Box type field to group multiple Radio boxes together.

format
string

Text format of the field. Used for the date type field only. Possible values are

  • m/d
  • m/d/yy
  • m/d/yyyy
  • mm/dd/yy
  • mm/dd/yyyy
  • mm/yy
  • mm/yyyy
  • d-mmm
  • d-mmm-yy
  • d-mmm-yyyy
  • dd-mmm-yy
  • dd-mmm-yyyy
  • yy-mm-dd
  • yyyy-mm-dd
  • mmm-yy
  • mmm-yyyy
  • mmmm-yy
  • mmmm-yyyy
  • mmmm d, yyyy
  • dd/mm/yy
  • ddmmmyyyy
value
string

Value that user want to show in the field.

max_length
required
integer <int32>

Maximum length of the value allowed in the field. Must between 1 - 9999

validation_rule
string

One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL".

object

Validations

object

Font of the fields text

multiline
required
boolean

This belongs to Text Area field type and If set to true, text area field would be created with multi line option.

Responses

Request samples

Content type
{
  • "search_text": "string",
  • "order": 0,
  • "placement": "string",
  • "field_type": "string",
  • "level_of_assurance": [
    ],
  • "dimensions": {
    },
  • "placeholder": "string",
  • "radio_group_name": "string",
  • "format": "string",
  • "value": "string",
  • "max_length": 0,
  • "validation_rule": "string",
  • "validation": {
    },
  • "font": {
    },
  • "multiline": true
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Document Field

Business applications can use this service API to delete a field of document in a package.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Name of the field to be deleted.

Responses

Request samples

Content type
{
  • "field_name": "string"
}

Response samples

Content type
application/json
{ }

Get Document Fields

Business applications can use this service API to get document fields i.e., initials, in-persons, signature fields or form fields.

path Parameters
packageId
required
integer <int64>

The ID of the package to which the document is added.

documentId
required
integer <int64>

The ID of the document for which the fields are requested.

pageNo
required
integer <int32>

Page no of the document for which the fields are requested. If page number is not provided fields of whole document are returned.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "signature": [
    ],
  • "hand_signature": [
    ],
  • "electronic_signature": [
    ],
  • "initials": [
    ],
  • "in_person_signature": [
    ],
  • "text": [
    ],
  • "radio": [
    ],
  • "checkbox": [
    ],
  • "dropdown": [
    ],
  • "listbox": [
    ],
  • "qrcode": [
    ]
}

Add Initial Field

Business applications can use this service API to add an initials field to a document in a package.

At least one user must exist in a workflow before fields(input and signature) can be added to the document in this way.The order number corresponds to the recipient in the workflow.Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

See Add Users to Workflow for more information. Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

The order of the user in workflow for which the field is being added.

page_no
required
integer <int32>

Page number on which the field is to be created.

field_name
string

Name of the field that is to be added. If not provided, system will assign an unique auto generated name to the field.

required
object (FieldDimension)

Responses

Request samples

Content type
{
  • "order": 0,
  • "page_no": 0,
  • "field_name": "string",
  • "dimensions": {
    }
}

Response samples

Content type
application/json
{
  • "field_name": "string"
}

Update Initial Field

Business applications can use this service API to update an initials field of a document in a package.

Note all of the input parameters can be changed.Where you wish to retain the current setting submit it in the call unchanged.

You can therefore use the same parameters as when you added the input field, or the information as returned by Get Document Fields.The latter can be used when a template was applied or the document was created using the GUI interface.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Current name of the field, that is to be updated.

renamed_as
string

Updated name of the field if renaming is intended.

page_no
required
integer <int32>

Page number on which the field is to be created.

required
object (FieldDimension)

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "renamed_as": "string",
  • "page_no": 0,
  • "dimensions": {
    }
}

Response samples

Content type
application/json
{ }

Add In-person Field

Business applications can use this service API to an add in-person signature field to a document in a package.

At least one user must exist in a workflow before fields(input and signature) can be added to the document in this way.The order number corresponds to the recipient in the workflow.Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

See Add Users to Workflow for more information. Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

In order to host an in-person meeting a SigningHub user must be part of the workflow.They must either be added with Role "INPERSON_HOST" or "SIGNER". For the host option they do not require a signature or input field on the document, and the in-person signature field can be signed by the non-SigningHub registered user.

Note this is a special workflow scenario whereby it is expected that the SigningHub user and recipient would be in the same location.This type of signature is not intended for use whereby a document is shared with recipients over email link in the normal loose integration method.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

The order of the user in workflow for which the field is being added.

page_no
required
integer <int32>

Page number on which the field is to be created.

field_name
string

Name of the field that is to be added. If not provided, system will assign an unique auto generated name to the field.

placeholder
required
string non-empty

String identifier for the inperson field, it can be Customer, Jack, CEO etc.

required
object (FieldDimension)
display
string

Visibility of the field that is to be added, possible values are "VISIBLE" and "INVISIBLE"

level_of_assurance
Array of strings

Level Of Assurance to be updated. Possible Values are "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL", "ELECTRONIC_SIGNATURE"

object (SignatureFieldAuthentication)

Responses

Request samples

Content type
{
  • "order": 0,
  • "page_no": 0,
  • "field_name": "string",
  • "placeholder": "string",
  • "dimensions": {
    },
  • "display": "string",
  • "level_of_assurance": [
    ],
  • "authentication_signing": {
    }
}

Response samples

Content type
application/json
{
  • "field_name": "string"
}

Update In-person Field

Business applications can use this service API to update an in-person signature field of a document in a package.

Note all of the input parameters can be changed.Where you wish to retain the current setting submit it in the call unchanged.You can therefore use the same parameters as when you added the input field, or the information as returned by Get Document Fields.The latter can be used when a template was applied or the document was created using the GUI interface.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Current name of the field, that is to be updated.

renamed_as
string

updated name of the field, if renaming is intended.

page_no
required
integer <int32>

Page number on which the field is to be created.

placeholder
string

String identifier for the in-person field, it can be Customer, Jack, CEO etc.

required
object (FieldDimension)
display
string

Visibility of the field that is to be updated, possible values are "VISIBLE" and "INVISIBLE"

level_of_assurance
Array of strings

Level Of Assurance to be updated. Possible Values are "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL", "ELECTRONIC_SIGNATURE"

object (SignatureFieldAuthentication)

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "renamed_as": "string",
  • "page_no": 0,
  • "placeholder": "string",
  • "dimensions": {
    },
  • "display": "string",
  • "level_of_assurance": [
    ],
  • "authentication_signing": {
    }
}

Response samples

Content type
application/json
{ }

Add Digital Signature Field

Business applications can use this service API to add a digital signature field to a document in a package.

At least one user must exist in a workflow before fields(input and signature) can be added to the document in this way.The order number corresponds to the recipient in the workflow.Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

See Add Users to Workflow for more information.Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

path Parameters
packageId
required
integer <int64>

The package ID for which workflow details need to be updated.

documentId
required
integer <int64>

The document ID where the field is to be added.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

Order of the recipient for which the field is being created.

page_no
required
integer <int32>

Page number at which the field is about to be created.

field_name
string

Name of the field that is to be added. If not provided, system will assign an unique auto generated name to the field.

level_of_assurance
required
Array of strings

Level Of Assurance to be added. Possible Values are "ELECTRONIC_SIGNATURE", "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SIGNATURE", "HIGH_TRUST_ADVANCED", "QUALIFIED_ELECTRONIC_SIGNATURE"

object (FieldDimension)
display
string

Visibility of the field that is to be added, possible values are "VISIBLE" and "INVISIBLE"

object (SignatureFieldAuthentication)

Responses

Request samples

Content type
{
  • "order": 0,
  • "page_no": 0,
  • "field_name": "string",
  • "level_of_assurance": [
    ],
  • "dimensions": {
    },
  • "display": "string",
  • "authentication_signing": {
    }
}

Response samples

Content type
application/json
{
  • "field_name": "string"
}

Update Digital Signature Field

Business applications can use this service API to update a digital signature field of a document in a package.

Note all of the input parameters can be changed.Where you wish to retain the current setting submit it in the call unchanged.You can therefore use the same parameters as when you added the input field, or the information as returned by Get Document Fields.The latter can be used when a template was applied or the document was created using the GUI interface.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Current name of the field, which is to be updated.

level_of_assurance
Array of strings

Level Of Assurance to be updated. Possible Values are "ELECTRONIC_SIGNATURE", "ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SEAL", "QUALIFIED_ELECTRONIC_SEAL", "ADVANCED_ELECTRONIC_SIGNATURE", "HIGH_TRUST_ADVANCED", "QUALIFIED_ELECTRONIC_SIGNATURE"

renamed_as
string

Updated name of the field if renaming of the field is intended.

page_no
required
integer <int32>

Page number on which the field is to be created.

required
object (FieldDimension)
display
string

Visibility of the field that is to be updated, possible values are "VISIBLE" and "INVISIBLE"

object (SignatureFieldAuthentication)

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "level_of_assurance": [
    ],
  • "renamed_as": "string",
  • "page_no": 0,
  • "dimensions": {
    },
  • "display": "string",
  • "authentication_signing": {
    }
}

Response samples

Content type
application/json
{ }

Add CheckBox Field

Business applications can use this service API to add a checkbox to a document in a package.

At least one user must exist in a workflow before fields(input and signature) can be added to the document in this way.The order number corresponds to the recipient in the workflow.Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

See Add Users to Workflow for more information. Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

The order of the user in workflow for which the field is being added.

page_no
required
integer <int32>

Page number on which the field is to be created.

field_name
string

Name of the provided field that is to be added. If not provided, system will assign an unique auto generated name to the field.

value
string

Value of the field. Possible values are "true" or "false"

required
object (FieldDimension)
validation_rule
string

One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL".

Responses

Request samples

Content type
{
  • "order": 0,
  • "page_no": 0,
  • "field_name": "string",
  • "value": "string",
  • "dimensions": {
    },
  • "validation_rule": "string"
}

Response samples

Content type
application/json
{
  • "field_name": "string"
}

Update CheckBox Field

Business applications can use this service API to update a checkbox field of a document in a package.

Note all of the input parameters can be changed.Where you wish to retain the current setting submit it in the call unchanged.You can therefore use the same parameters as when you added the input field, or the information as returned by Get Document Fields.The latter can be used when a template was applied or the document was created using the GUI interface.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Current name of the field, that is to be updated.

renamed_as
string

Updated name of the field if renaming is intended.

page_no
required
integer <int32>

Page number on which the field is to be created.

value
string

Value of the field.

required
object (FieldDimension)
validation_rule
string

One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL".

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "renamed_as": "string",
  • "page_no": 0,
  • "value": "string",
  • "dimensions": {
    },
  • "validation_rule": "string"
}

Response samples

Content type
application/json
{ }

Add TextBox Field

Business applications can use this service API to add a text input field to a document in a package.

At least one user must exist in a workflow before fields(input and signature) can be added to the document in this way.The order number corresponds to the recipient in the workflow.Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

See Add Users to Workflow for more information. Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

The order of the user in workflow for which the field is being added.

page_no
required
integer <int32>

Page number on which the field is to be created.

type
required
string
Enum: "TEXT" "NAME" "EMAIL" "COMPANY" "JOBTITLE" "DATE"
value
string

Value of the field. For type = DATE, the value is expected to follow ISO 8601 format.Following the format YYYY-MM-DD hh:mm:ss +00. As the values are for date fields client applications can send YYYY-MM-DD and ignore hh:mm:ss +00. If value is not in proper format an error will be returned.

placeholder
string

Placeholder text for the text field. For name, email, company, job title and date, placeholder value can be "NAME", "EMAIL", "COMPANY", "JOBTITLE", "DATE". Developers can send their own placeholders to overwrite the default values. For "TEXT" developers can provide a their own placeholder texts. These placeholders appear in the text fields while viewing the document in viewer.

max_length
required
integer <int32>

Maximum length of the value allowed in the field. Must between 1 - 9999

format
string

Text format of the field. Used for the date type field only. Possible values are

  • m/d
  • m/d/yy
  • m/d/yyyy
  • mm/dd/yy
  • mm/dd/yyyy
  • mm/yy
  • mm/yyyy
  • d-mmm
  • d-mmm-yy
  • d-mmm-yyyy
  • dd-mmm-yy
  • dd-mmm-yyyy
  • yy-mm-dd
  • yyyy-mm-dd
  • mmm-yy
  • mmm-yyyy
  • mmmm-yy
  • mmmm-yyyy
  • mmmm d, yyyy
  • dd/mm/yy
  • ddmmmyyyy
field_name
string

Name of the field that is to be added. If not provided, system will assign an unique auto generated name to the field.

field_type
required
string
Enum: "Number" "Text"
validation_rule
required
string
Enum: "OPTIONAL" "MANDATORY"
object

Validations

required
object

Font of the fields text

required
object (FieldDimension)
multiline
required
boolean

If set to true, multilne text field would be created

Responses

Request samples

Content type
{
  • "order": 0,
  • "page_no": 0,
  • "type": "TEXT",
  • "value": "string",
  • "placeholder": "string",
  • "max_length": 0,
  • "format": "string",
  • "field_name": "string",
  • "field_type": "Number",
  • "validation_rule": "OPTIONAL",
  • "validation": {
    },
  • "font": {
    },
  • "dimensions": {
    },
  • "multiline": true
}

Response samples

Content type
application/json
{
  • "field_name": "string"
}

Update TextBox Field

Business applications can use this service API to update a text box of a document in a package.

Note all of the input parameters can be changed.Where you wish to retain the current setting submit it in the call unchanged. You can therefore use the same parameters as when you added the input field, or the information as returned by Get Document Fields. The latter can be used when a template was applied or the document was created using the GUI interface.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Current name of the field, that is to be updated.

renamed_as
string

Updated name of the field if renaming is intended.

page_no
required
integer <int32>

Page number on which the field is to be created.

value
string

Value of the field. For type = DATE, the value is expected to follow ISO 8601 format.Following the format YYYY-MM-DD hh:mm:ss +00. As the values are for date fields client applications can send YYYY-MM-DD and ignore hh:mm:ss +00. If value is not in proper format an error will be returned.

max_length
required
integer <int32>

Maximum length of the value allowed in the field. Must between 1 - 9999

field_type
required
string
Enum: "Number" "Text"
validation_rule
required
string
Enum: "OPTIONAL" "MANDATORY"
object

Font of the fields text

object (FieldDimension)
placeholder
string

Developers can provide a their own placeholder texts. These placeholders appear in the text fields while viewing the document in viewer.

format
string

Text format of the field. Used for the date type field only. Possible values are

  • m/d
  • m/d/yy
  • m/d/yyyy
  • mm/dd/yy
  • mm/dd/yyyy
  • mm/yy
  • mm/yyyy
  • d-mmm
  • d-mmm-yy
  • d-mmm-yyyy
  • dd-mmm-yy
  • dd-mmm-yyyy
  • yy-mm-dd
  • yyyy-mm-dd
  • mmm-yy
  • mmm-yyyy
  • mmmm-yy
  • mmmm-yyyy
  • mmmm d, yyyy
  • dd/mm/yy
  • ddmmmyyyy
object

Validations

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "renamed_as": "string",
  • "page_no": 0,
  • "value": "string",
  • "max_length": 0,
  • "field_type": "Number",
  • "validation_rule": "OPTIONAL",
  • "font": {
    },
  • "dimensions": {
    },
  • "placeholder": "string",
  • "format": "string",
  • "validation": {
    }
}

Response samples

Content type
application/json
{ }

Add RadioBox Field

Business applications can use this service API to add a checkbox to a document in a package.

At least one user must exist in a workflow before fields(input and signature) can be added to the document in this way.The order number corresponds to the recipient in the workflow.Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

See Add Users to Workflow for more information. Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
order
required
integer <int32>

The order of the user in workflow for which the field is being added.

page_no
required
integer <int32>

Page number on which the field is to be created.

field_name
string <= 255 characters

Name of the provided field that is to be added. If not provided, system will assign an unique auto generated name to the field.

value
string

Value of the field. Possible values are "true" or "false"

validation_rule
required
string
Enum: "OPTIONAL" "MANDATORY"
radio_group_name
required
string non-empty
required
object (FieldDimension)

Responses

Request samples

Content type
{
  • "order": 0,
  • "page_no": 0,
  • "field_name": "string",
  • "value": "string",
  • "validation_rule": "OPTIONAL",
  • "radio_group_name": "string",
  • "dimensions": {
    }
}

Response samples

Content type
application/json
{
  • "field_name": "string"
}

Update RadioBox Field

Business applications can use this service API to update a radio button of a document in a package.

Note all of the input parameters can be changed.Where you wish to retain the current setting submit it in the call unchanged.You can therefore use the same parameters as when you added the input field, or the information as returned by Get Document Fields.The latter can be used when a template was applied or the document was created using the GUI interface.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string [ 1 .. 255 ] characters

Current name of the field, that is to be updated.

renamed_as
string

Updated name of the field if renaming is intended.

page_no
required
integer <int32>

Page number on which the field is to be created.

value
string

Value of the field.

validation_rule
required
string
Enum: "OPTIONAL" "MANDATORY"
radio_group_name
required
string non-empty

The group name to which the field belongs.

required
object (FieldDimension)

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "renamed_as": "string",
  • "page_no": 0,
  • "value": "string",
  • "validation_rule": "OPTIONAL",
  • "radio_group_name": "string",
  • "dimensions": {
    }
}

Response samples

Content type
application/json
{ }

Add QR Code

Business applications can use this service API to add a QR Code to a document in a package.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
page_no
required
integer <int32>

Page number on which the field is to be created.

field_name
string <= 255 characters

Name of the provided field that is to be added. If not provided, system will assign an unique auto generated name to the field.

required
object

Field dimensions

Responses

Request samples

Content type
{
  • "page_no": 0,
  • "field_name": "string",
  • "dimensions": {
    }
}

Response samples

Content type
application/json
{
  • "field_name": "string",
  • "value": "string"
}

Update QR Code

Business applications can use this service API to update a QR Code of a document in a package.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The document ID for which the action is to be taken.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string [ 1 .. 255 ] characters

Current name of the field, that is to be updated.

renamed_as
string

Updated name of the field if renaming is intended.

page_no
required
integer <int32>

Page number for which field is need to be updated

required
object

Field dimensions

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "renamed_as": "string",
  • "page_no": 0,
  • "dimensions": {
    }
}

Response samples

Content type
application/json
{ }

Document Processing

This section entails the web services for the Document Processing i.e. Sign Document, Recall Document, Bulk Sign, and Finish Workflow.

Recall Document

Business applications can use this service API to stop a workflow in progress. The document ID is provided in the resource URL. After recall the document status automatically changes to “DRAFT”.

path Parameters
packageId
required
integer <int32>

The ID of the package to be recalled.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Approve Document

Business applications can use this service API to approve a document by a specified user in the order.

path Parameters
packageId
required
integer <int64>

The ID of the package to be approved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Request Body schema:
reason
string

The reason for approving a package.

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
application/json
{ }

Gatekeeper Approve Document

Business applications can use this service API to gatekeeper approve a document by a specified user in the order.

path Parameters
packageId
required
integer <int64>

The ID of the package to be approved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Request Body schema:
reason
string

The reason for approving a package.

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
application/json
{ }

Decline Document

Business applications can use this service API to decline a document by a specified user in the order.

path Parameters
packageId
required
integer <int64>

The ID of the package to be declined.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
reason
string

Reason provided by the user for declining.

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
application/json
{ }

Gatekeeper Decline Document

Business applications can use this service API to gatekeeper decline a document by a specified user in the order.

path Parameters
packageId
required
integer <int64>

The ID of the package to be declined.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
reason
string

Reason provided by the user for declining.

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
application/json
{ }

Finish Processing

Business applications can use this service API to finish the document processing after signing all the signature fields. This method is primarily used by native SigningHub mobile apps for iOS and Android, and mobile web use cases. General business applications employing tight integration into their respective portal do not need to call this method. However, when using the Sign Document API (and hence the user is not presented with a visual representation of the document they are requested to sign) calling this API is required in order to ensure the respective workflow continues or completes. For example, once all signatures have been applied using the "blind" Sign Document API call the document will not show as status "Completed" to the owner until this API is invoked. The document owner will see a status of "In Progress" until this API is called.

Within native SigningHub mobile apps and mobile web use cases, this call is necessary to ensure that each user completes their respective actions with respect to SigningHub.For example, after a signatory has signed a document in SigningHub App, this method is invoked by the application to ensure the workflow continues to process and the next signatory is notified, and the document status is available via the configured call-back URL.

path Parameters
packageId
required
integer <int32>

The ID of the package to be finished.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Submit Document

One of the SigningHub roles is called "Editor". This allows a recipient to edit input fields on a document, but does not require a signature. Once completed the recipient submits their changes. The button used in the GUI is called "Submit".

This is the equivalent operation for an editor to submit their changes via an API call.

Click SigningHub Roles for a description of all available workflow recipient roles.

path Parameters
packageId
required
integer <int64>

The SigningHub package ID that contains the document to be submitted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Responses

Response samples

Content type
application/json
{ }

Bulk Sign Packages

Business applications can use this API to sign multiple documents (both electronic and digital) without displaying the documents to the end user. This API needs information from the business application about document packages and the details of signatures, in-person and initials fields. On the successful completion of bulk signing transaction, the API will return the statuses and transaction ids of the document packages.

Unlike the Sign Document API, this API not only signs a document package but also marks it as approved and reviewed based on whether the recipient is a Signer, Editor or Reviewer. Any document package for which the status returns as COMPLETED has been signed, approved or reviewed by this API.

Bulk Signing works with all the signing-time authentication methods.

You must call this API after the Pre Bulk Sign Documents API.

In case you need to make changes in any of the document before signing, the Fill Form Fields API should be called before calling the Pre Bulk Sign Document API. Remember, any mandatory input fields on a document require completing before this API will successfully complete; whereas, the auto-populated fields (like Name, Email, Date, Job Title, etc.) will be automatically filled.

The signatory is identified by the access token presented in the call. Therefore, authentication of the signatory is required prior to making this call. You cannot authenticate as an Enterprise Admin with the scope variable, and sign a document on behalf of a user. The access token must be issued to the signatory as a result of direct authentication.

Once document is signed, the verification response can be seen from the Bulk Signing Status API.

First or Second Factor OTP Usage for Authentication

In case OTP authentication is turned on for the server side signing operation, the client applications will need to generate an OTP for the mobile number using the Bulk Sign Authentication via OTP API call. Respective business applications must retrieve the OTP from the use and submit it when making the API call. This is done using the "x-otp" header in the request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-otp
string
Default: 456789

OTP used as a second factor authentication for the signing operation.

Request Body schema:
ids
Array of integers <int64> [ items <int64 > ]

An array of the document package ids that are selected for bulk signing.

hand_signature_initials_image
string

Base64 image used for the filling of the initials

hand_signature_image
string

Base64 encoded string image of the visible signature appearance

signing_reason
string

Reason of signing provided by the recipient.

signing_location
string

Locale of the signer provided by the recipient

contact_information
string

Contact information of the signer provided by the recipient

appearance_design
string

Name of the signature appearance provided by user for signing. In case no appearance name is provided then default selected appearance would be used. Possible values are "COMPANY_LOGO", "DETAILED_SIGNATURE", "HAND_SIGNATURE"

signing_server
string

Name of signing server using which the document is to be signed

signing_capacity
string

Name of certification profile/signing capacity using which the document is to be signed

object

Authentication object is an optional, it contains authentication releated options

transaction_id
string

re-initiated signing process transaction id

Responses

Request samples

Content type
{
  • "ids": [
    ],
  • "hand_signature_initials_image": "string",
  • "hand_signature_image": "string",
  • "signing_reason": "string",
  • "signing_location": "string",
  • "contact_information": "string",
  • "appearance_design": "string",
  • "signing_server": "string",
  • "signing_capacity": "string",
  • "authentication": {
    },
  • "transaction_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "transaction_id": "string"
}

Bulk Signing Status

Business applications can use this API to get the status of a specific bulk signing transaction along with the details of document packages that were processed by the Bulk Signing Packages API.

You must call this API after the Bulk Signing Packages API.

The signatory is identified by the access token presented in the call. Therefore, authentication of the signatory is required prior to making this call. You cannot authenticate as an Enterprise Admin with the scope variable, and sign a document on behalf of a user. The access token must be issued to the signatory as a result of direct authentication.

For RAS signing, the ACTION property will be REMOTE_AUTHORIZATION_REQURIED and the STATUS property will be PENDING, indicating that the request needs to be authorized using the mobile device. If the signing process fails in some document due to different levels of assurance configured and the user wants to re-initiate the signing process to complete the signing process on failed documents, the ACTION property will be REINITIATE_SIGNING_PROCESS, and the STATUS property will be COMPLETED.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
transaction_id
string

The identification number of the bulk signing transaction

Responses

Request samples

Content type
{
  • "transaction_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "packages": [
    ]
}

Authorization Signing Request Status

Applications can use this API to get the status of authorized signing request against provided signature field name.

path Parameters
packageId
required
integer <int64>
documentId
required
integer <int64>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
string

Name of signature field.

Responses

Request samples

Content type
{
  • "field_name": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Signer Authentication via OTP (Users, In-persons, E-Signers)

Business applications can use this service API to generate an OTP while signing an electronic signature field or in-person field. Same service can be used to authenticate OTP for a user signing digital signature field. An OTP will be sent to the mobile number saved in user profile settings. If no phone number is found it will throw an error.

path Parameters
packageId
required
integer <int64>

ID of the package to which the document is added.

documentId
required
integer <int64>

The ID of the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Unique identifier of the field in the document.

method
string

Method Possible values are "EMAIL", "SMS"

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "method": "string"
}

Response samples

Content type
application/json
{ }

OTP Bulk Signing Authentication

Business applications can use this API to generate an OTP (based on the OTP settings configured in Enterprise Role) while performing bulk signing operation on the selected document packages. An OTP will be sent to the mobile number saved in the user profile settings. If no phone number is found it will throw an error.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:

The OTP method.

method
string

Method Possible values are "EMAIL", "SMS"

Responses

Request samples

Content type
{
  • "method": "string"
}

Response samples

Content type
application/json
{ }

Sign Document

Business applications can use this service API to sign a document (both electronic and digital) without displaying the document to the end user using SigningHub. For example, a business application may have another method to display the document to the user, and only the signing functionality of SigningHub is required, or for bulk operations it may be justified to sign without requiring the user to view and approve every document individually. If there are changes to be saved in the document before signing, Fill Form Fields API should be called before calling the Sign Document API. Note any mandatory input fields on a document require completing before this API will successfully complete.

The signatory is identified by the access token presented in the call.Therefore, authentication of the signatory is required prior to making this call.You cannot authenticate as an Enterprise Admin with the scope variable, and sign a document on behalf of a user.The access token must be issued to the signatory as a result of direct authentication.

When this call completes it is important that if the signatory was the last signer for a document that the Finish Document API call is invoked.The reason is because without calling that API the document will remain in a status of "In Progress" to the document owner. Once the API has been called, the status will change to "Completed" for the document owner.

Once document is signed, the verification response can be seen from Get Document Verification API.

First or Second Factor OTP Usage for Authentication

If OTP authentication is turned on for the server side signing operation, client applications will need to generate a OTP for the mobile number using Signer Authentication via OTP API call. Respective business applications must retrieve the OTP from the use and submit it when making the API call. This is done using the "x-otp" header in the request.

path Parameters
packageId
required
integer <int64>

The identifier of the package that contains the document for signature.

documentId
required
integer <int64>

Identifier of the document to be signed.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication. As stated above, the "scope" variable cannot be used in this instance. Only the authenticated user can sign documents using this API call.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-otp
string
Default: 456789

OTP used as a second factor authentication for the signing operation.

Request Body schema:
field_name
required
string non-empty

Unique identifier of the signature field in the document.

hand_signature_image
string

Base64 encoded string image of the visible signature appearance, which is placed onto the document. Note this can be retrieved from the user's personal settings using this call. (The response is binary, so the business application must then Base64 encode it before submitting in this API call.)

signing_reason
string

Reason of signing provided by the recipient.

signing_location
string

Locale of the signer provided by the recipient.

contact_information
string

Contact information of the signer provided by the recipient.

user_name
string

Name of the signer provided by the recipient. Note this applies to in-person signing operations only.

user_password
string

Password provided by the user subject to user's signature settings.

appearance_design
string

Name of the signature appearance provided by user for signing. In case no appearance name is provided then default selected appearance would be used. Possible values are "COMPANY_LOGO","DETAILED_SIGNATURE","HAND_SIGNATURE"

signing_capacity
string

Name of certification profile/signing capacity using which the document is to be signed. If not provided the default capacity will be used to sign. Provided name must be exactly same as of the actual profile due to case sensitivity.

skip_verification
required
boolean

No signature verification returns in response body when it is set as true. Default value for this parameter set to false.

signing_server
string

Name of signing server using which the document is to be signed.

object

Authentication object is an optional, it contains authentication releated options

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "hand_signature_image": "string",
  • "signing_reason": "string",
  • "signing_location": "string",
  • "contact_information": "string",
  • "user_name": "string",
  • "user_password": "string",
  • "appearance_design": "string",
  • "signing_capacity": "string",
  • "skip_verification": true,
  • "signing_server": "string",
  • "authentication": {
    }
}

Response samples

Content type
application/json
{
  • "field_name": "string",
  • "status": "string",
  • "transaction_id": "string",
  • "verification": {
    }
}

Pre Validate Bulk Signing

This API executes pre-signing validations for each document package and respectively returns any errors along with the list of tasks that the business application needs to perform for completing the signing process. The API call will be sent by business application and will wait for the server's response. It's a synchronous call, which means the business applications need to show a loader.

You must call this API before any other bulk signing APIs.

This call should not be skipped as it provides the necessary information to the business application regarding which dialog needs to be shown including capacities and also if there is legal notice is required or not.

The signatory is identified by the access token presented in the call. Therefore, authentication of the signatory is required prior to making this call. You cannot authenticate as an Enterprise Admin with the scope variable, and sign a document on behalf of a user. The access token must be issued to the signatory as a result of direct authentication.

Once this API returns the response according to your needs, you can then perform bulk signing via Bulk Signing Packages API.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
ids
Array of integers <int64> [ items <int64 > ]

An array of the document package ids that are selected for bulk signing.

Responses

Request samples

Content type
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "failed_packages": [
    ],
  • "tasks": {
    }
}

Get Registered Devices

This API can be used to check if a device is already registered for authorized remote signing.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Cancel Authorize Signing Request

Applications can use this API to cancel the authorized signing request against provided transaction id.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
transaction_id
required
string non-empty

state that need to cancel

Responses

Request samples

Content type
{
  • "transaction_id": "string"
}

Response samples

Content type
application/json
{ }

Fill Form Fields

Business applications can use this service API to fill one or more form fields in a document by a specified user in the order.

path Parameters
packageId
required
integer <int64>

Package ID to which the document is added.

documentId
required
integer <int64>

The ID of the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: pincode123

Password of the document, if a document opening password was set by the document owner for the recipient. Otherwise null or ignore.

x-otp
string
Default: 123456

OTP value for opening the document, if a document opening OTP permission was set by the document owner. Otherwise null or ignore.

Request Body schema:
auto_save
required
boolean

Default value is false. True, if the form fields are being saved without user intervention e.g., while closing the document or pressing back. For Signing, Initials, In-persons, Reviewing, Submit actions the value is false.

Array of objects (TextFormFillingRequest)

It has the list of textboxes data to save

Array of objects (RadioFormFillingRequest)

It has the list of radios value to save

Array of objects (CheckBoxFormFillingRequest)

It has the list of checkboxes value to save

Array of objects (DropDownFormFillingRequest)

It has the list of dropdowns value to save

Array of objects (ListBoxFormFillingRequest)

It has the list of listboxes value to save

Responses

Request samples

Content type
{
  • "auto_save": true,
  • "text": [
    ],
  • "radio": [
    ],
  • "checkbox": [
    ],
  • "dropdown": [
    ],
  • "listbox": [
    ]
}

Response samples

Content type
application/json
{ }

Fill Initials

Business applications can use this service API to fill an initials field in a document by a specified user in the order.

path Parameters
packageId
required
integer <int64>
documentId
required
integer <int64>

The ID of the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
field_name
required
string non-empty

Unique identifier of the field in the document.

image
required
string non-empty

Base64 image used for the filling of the initials.

apply_to_all
required
boolean

True if all initials are to be filled.

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "image": "string",
  • "apply_to_all": true
}

Response samples

Content type
application/json
{ }

Enterprise Management

Enterprise management refers to SigningHub Enterprise account management.  This differs from SigningHub Administration and is a lower privilege level.

The Enterprise level allows enterprise administrators to manage a group or set of users.  This is the most common use case scenario of SigningHub, and is a mandatory requirement for using the APIs.

This set of APIs allows an Enterprise Administrator to administer users under their control.

Register Enterprise User

Business applications can use this service API to register Enterprise Users into their Enterprise account. New users inherit the Enterprise Admin Service Plan and all associated permissions. Furthermore, the role assigned to them dictates what functionality they will have available to them. The Role dictates things such as allowed authentication methods to access the system and signing capacities available to the user. Enterprise Roles are described in detail here.

There are different scenarios to consider when registering a user.When "Protect server-side signing keys with user password" option is "Enabled" in Enterprise Admin Service Plan, then:

● User will get an "account activation" email on successfull registartion, if password, security question and answer parameters are not provided in the call.Email notification flag would be ignored by the system in this case.

● User will get an "account registration" email on successfull registartion, if password, security question and answer parameters are provided in the call. Email notification flag should be set to True in this case

● User will not get any email on successfull registartion, if password, security question and answer parameters are provided in the call and email notification flag is set to False

When "Protect server-side signing keys with user password" option is "Disabled" in Enterprise Admin Service Plan, then:

● User will get an "account registration" email on successfull registartion, if password, security question and answer parameters are provided in the call. Email notification flag should be set to True in this case.

● User will not get any email on successfull registartion, if password, security question, answer details are either provided or not and email notification flag is to set False

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_name
required
string non-empty

The name of the user to be registered.

user_email
required
string non-empty

The email address of the user account to be registered.

user_password
string

The password of the user account. This is optional if you want your users to authenticate externally e.g. via SAML, Salesforce, Office 365 etc. rather than using a SigningHub ID (email/password). If password is provided, application expects the security question and answer as mandatory fields.

security_question
string

Security question used to reset password if user forgets his password. This is mandatory if you wish to allow the user to sign without manually, via an email link, completing the registration process. If security question is provided, application expects password and security answer as mandatory fields.

security_answer
string

Security answer used to reset the password if user forgets his password. This is mandatory if you wish to allow the user to sign without manually, via an email link, completing the registration process. If security answer is provided, application expects password and security question as mandatory fields.

enterprise_role
string

The enterprise role to be assigned to this user - these are managed within the Enterprise account.

email_notification
boolean

This defines whether enterprise user would get an email notification about the account creation. Default value is 'false'.

certificate_id
string
job_title
string

Job title of user.

company_name
string

Company name of user.

mobile_number
string

Mobile number of user.

country
string

Country name for the user. All values in the appendix - Country list are accepted.

time_zone
string

Timezone name for the user. All values in the appendix - Timezone list are accepted.

language
string

Language selected for the user. All values in the appendix - Language list are accepted.

user_national_id
string

National identity number of the user. This helps to identify user in the workflow

user_csp_id
string

User ID of the user registered in CSP service inside SigningHub Engine (ADSS Server).

user_ra_id
string

User ID of the user registered in SAM service inside SigningHub Engine (ADSS Server).

common_name
string

An identifiable name for the user that added as Common Name (CN) in identity certificate.

Responses

Request samples

Content type
{
  • "user_name": "string",
  • "user_email": "string",
  • "user_password": "string",
  • "security_question": "string",
  • "security_answer": "string",
  • "enterprise_role": "string",
  • "email_notification": true,
  • "certificate_id": "string",
  • "job_title": "string",
  • "company_name": "string",
  • "mobile_number": "string",
  • "country": "string",
  • "time_zone": "string",
  • "language": "string",
  • "user_national_id": "string",
  • "user_csp_id": "string",
  • "user_ra_id": "string",
  • "common_name": "string"
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

Get Enterprise Users

Business applications can use this service API to get the list of all the registered Enterprise Users within their Enterprise. The search field (x-search-text header) is for email address input or part thereof to handle wildcards or "emails like". There is no requirement to supply wildcard characters in the search. For example, a search string of "sh18" would find and return "sh18@ascertia.com" Enterprise User.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: IGpvaG5AYXNjZXJ0aWEuY29t

Search text if required. This is optional and without it the entire list is returned.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Enterprise User

Business applications can use this service API to update the information of an enterprise user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

The email address of the user account to be updated.

user_name
string

The name of the user to be updated.

job_title
string

Job title of user.

company_name
string

Company Name of user.

mobile_number
string

Mobile number of user.

user_old_password
string

The old password of the user account.

user_new_password
string

The new password of the user account.

security_question
string

Security question used to reset password if user forgets his password.

security_answer
string

Security answer used to reset the password if user forgets his password.

enterprise_role
string

The enterprise role to be assigned to this user - these are managed within the Enterprise account.

enabled
boolean

Setting this to false would disable the user and vice versa

country
string

Country name for the user. All values in the appendix - Country list are accepted.

time_zone
string

Timezone name for the user. All values in the appendix - Timezone list are accepted.

language
string

Language selected for the user. All values in the appendix - Language list are accepted.

user_national_id
string

National identity number of the user.

common_name
string

An identifiable name for the user that added as Common Name (CN) in identity certificate.

user_ra_id
string

User ID of the user registered in SAM service inside SigningHub Engine (ADSS Server).

user_csp_id
string

User ID of the user registered in CSP service inside SigningHub Engine (ADSS Server)

Responses

Request samples

Content type
{
  • "user_email": "string",
  • "user_name": "string",
  • "job_title": "string",
  • "company_name": "string",
  • "mobile_number": "string",
  • "user_old_password": "string",
  • "user_new_password": "string",
  • "security_question": "string",
  • "security_answer": "string",
  • "enterprise_role": "string",
  • "enabled": true,
  • "country": "string",
  • "time_zone": "string",
  • "language": "string",
  • "user_national_id": "string",
  • "common_name": "string",
  • "user_ra_id": "string",
  • "user_csp_id": "string"
}

Response samples

Content type
application/json
{ }

Delete Enterprise User

Business applications can use this service API to delete an enterprise user from its enterprise account. If “x-permanent” is sent with the value true in the headers it will delete the user from the system. The email address of the user to be deleted is provided in JSON request body as “user_email”.

If user has any pending documents, then these are automatically declined as result of delete operation.If user has shared documents, then the documents are automatically recalled and workflow is stopped for all these documents.The documents of the user are also deleted as part of user deletion.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-permanent
string
Default: true

True, if users are to be deleted permanently from the application. If false it will only be removed from the enterprise and converted to a default individual user with a trial account.

Request Body schema:
user_email
required
string non-empty

The email address of the enterprise user to be deleted.

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{ }

Add Enterprise User Signing Certificates

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email address of the account owner.

capacity_name
required
string [ 1 .. 100 ] characters

capacity name

certificate_alias
required
string [ 1 .. 255 ] characters

certificate alias

isDefault
required
boolean

Capacity set as Default

level_of_assurance
required
string non-empty

Signature Type ADVANCED_ELECTRONIC_SIGNATURE | HIGH_TRUST_ADVANCED | QUALIFIED_ELECTRONIC_SIGNATURE

key_protection_option
required
string non-empty

Key protected by USER_PASSWORD | REMOTE_AUTHORISATION

certificate
string

Certificate base64

Responses

Request samples

Content type
{
  • "user_email": "string",
  • "capacity_name": "string",
  • "certificate_alias": "string",
  • "isDefault": true,
  • "level_of_assurance": "string",
  • "key_protection_option": "string",
  • "certificate": "string"
}

Response samples

Content type
application/json
{
  • "id": 0
}

Update Enterprise User Signing Certificates

path Parameters
usercertificateid
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email address of the account owner.

capacity_name
string <= 100 characters

capacity name

certificate_alias
string <= 255 characters

certificate alias

isDefault
required
boolean

Capacity set as Default

level_of_assurance
required
string non-empty

Signature Type ADVANCED_ELECTRONIC_SIGNATURE | HIGH_TRUST_ADVANCED | QUALIFIED_ELECTRONIC_SIGNATURE

certificate
string

Certificate base64

Responses

Request samples

Content type
{
  • "user_email": "string",
  • "capacity_name": "string",
  • "certificate_alias": "string",
  • "isDefault": true,
  • "level_of_assurance": "string",
  • "certificate": "string"
}

Response samples

Content type
application/json
{ }

Delete Enterprise User Signing Certificates

path Parameters
usercertificateid
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email address of the account owner.

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{ }

Get Enterprise Invitations

Business applications can use this service API to get the invited users list.

path Parameters
pageNo
required
integer <int32>

Page number, according the division of records per page.

recordsPerPage
required
integer <int32>

Number of records that are needed to be fetched in one request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Enterprise User Invitation

Business applications can use this service API to delete an invitation already sent to an enterprise user. The email address of the user for whom the invitation is to be deleted is provided in JSON request body as “user_email”.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

The email address of the enterprise user for which the invitation is to be deleted.

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{ }

Invite Enterprise User

Business applications can use this API to invite existing or new SigningHub users to join an Enterprise account. The invited users can be individuals or part of another Enterprise. The invited users would get an invitation email and users would be required to click the link provided in email to accept the invitation. If a user in an Enterprise accepts this invitation they are unlinked from the existing Enterprise and will join the new enterprise.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_name
required
string non-empty

The name of the user to be invited.

user_email
required
string non-empty

The email address of the user account to be invited.

enterprise_role
string

The enterprise role under which the user should be invited.

Responses

Request samples

Content type
{
  • "user_name": "string",
  • "user_email": "string",
  • "enterprise_role": "string"
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

Get Groups

Business applications can use this service API to get the list of groups for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

It is possible to search based upon the criterion supplied under the "x-search-text" header.Furthermore, it is possible to search a user's personal groups or that of the enterprise to which the user belongs.

The response contains both the group name and the members thereof.Group member details returned are email address and user name.

path Parameters
recordPerPage
required
integer <int32>

Total number of records to be retrieved in a page.

pageNo
required
integer <int32>

Page number to be retrieved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: U2FsZXM=

Search text if required. This is optional and without it the entire list is returned.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-enterprise
string
Default: true

If set as "true" only enterprise groups list will be returned. In case of "false"only the user's groups list will be returned.If you do not set the header, then both enterprise and user's groups lists will be returned.

x-total-records
string
Example: 10

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Enterprise Group

Business applications can use this service API to update group information for Enterprise Groups. An enterprise Admin or the enterprise user who has permissions to manage enterprise groups in this role, can update groups.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Name
required
string [ 1 .. 255 ] characters

Group Name

Description
string

Group Description

required
Array of objects (GroupMembers)

Responses

Request samples

Content type
{
  • "Name": "string",
  • "Description": "string",
  • "Members": [
    ]
}

Response samples

Content type
application/json
{ }

Delete Enterprise Group

Business applications can use this service API to delete enterprise group for its users. An enterprise Admin or the enterprise user who has permissions to manage users in this role, can delete enterprise groups for user. The role dictates things such as allowed delete groups available to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Get Enterprise Group

Business applications can use this service API to get enterprise group for its users. An enterprise Admin or the enterprise user who has permissions to manage users in this role, can get enterprise groups for user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "members": [
    ]
}

Add Enterprise Group

Business applications can use this service API to add a group for Enterprise Users. An enterprise Admin or the enterprise user who has permissions to manage enterprise groups in this role, can add new groups.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Name
required
string [ 1 .. 255 ] characters

Group Name

Description
string

Group Description

required
Array of objects (GroupMembers)

Responses

Request samples

Content type
{
  • "Name": "string",
  • "Description": "string",
  • "Members": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string"
}

Get Enterprise Branding

Business application can use this API call to retrieve the default branding of SigningHub Application that is set by at the enterprise administrator level. This includes the logo, favicon and colours that comprise the branding options. Note this is not to be confused with the SigningHub Administration level branding. For these settings click here.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" or "active_directory" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
string
Default: true

Responses

Response samples

Content type
application/json
{
  • "logo": "string",
  • "logo_url": "string",
  • "favicon": "string",
  • "favicon_url": "string",
  • "colors": {
    }
}

Get Enterprise Branding Favicon

Business application can get the application favicon configured in the enterprise branding.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Reset Enterprise Emails To Default

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Enterprise Legal Notice

Business applications can use this service API to get a legal notice for Enterprise Users into their Enterprise account. An enterprise Admin who has permissions to manage Advanced Settings in his role, can Read a legal notice. The role dictates things such as allowed Get advanced settings to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "content": "string"
}

Update Enterprise Legal Notice

Business applications can use this service API to edit a legal notice for Enterprise Users into their Enterprise account. An enterprise Admin who has permissions to manage Advanced Settings in his role, can edit a legal notice. The role dictates things such as allowed Edit advanced settings to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
title
required
string [ 1 .. 255 ] characters

Legal Notice Title

content
required
string non-empty

Legal Notice Content

Responses

Request samples

Content type
{
  • "title": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{ }

Delete Enterprise Legal Notice

Business applications can use this service API to delete a legal notice for Enterprise Users into their Enterprise account. An enterprise Admin who has permissions to manage Advanced Settings in his role, can delete a legal notice. The role dictates things such as allowed Delete advanced settings to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Add Enterprise Legal Notice

Business applications can use this service API to add a legal notice for Enterprise Users into their Enterprise account. An enterprise Admin who has permissions to manage Advanced Settings in his role, can add a legal notice. The role dictates things such as allowed Add advanced settings to the user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" or "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
title
required
string [ 1 .. 255 ] characters

Legal Notice Title

content
required
string non-empty

Legal Notice Content

Responses

Request samples

Content type
{
  • "title": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "id": 0
}

V4_Enterprise_GetEnterprisePackages

path Parameters
document_status
required
string
Enum: "ALL" "DRAFT" "INPROGRESS" "PENDING" "SIGNED" "COMPLETED" "REVIEWED" "DECLINED" "EDITED" "EXPIRING_IN_SEVEN_DAYS"
page_no
required
integer <int32>
records_per_page
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: c2FsZXMgY29udHJhY3QgMTA1

Search text sent in headers for further filtration of the documents. Package id, name and document owner can be searched.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-total-records
string
Example: 212

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Enterprise Package

Business applications can use this service API to get a list of enterprise document.

path Parameters
packageId
required
integer <int64>

Package ID of the document package.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "package_id": 0,
  • "package_name": "string",
  • "package_owner": "string",
  • "owner_name": "string",
  • "package_status": "string",
  • "folder": "string",
  • "unread": true,
  • "next_signer": "string",
  • "next_signer_email": [
    ],
  • "uploaded_on": "string",
  • "modified_on": "string",
  • "access_duration": {
    },
  • "decline": {
    }
}

Delete Enterprise Package

Business applications can use this service API to delete an enterprise document from the user inbox. The package ID is provided in the resource URL as "{package_id}". If the document status is PENDING, then it is automatically declined as result of delete operation. If the document status is SHARED, then the document is automatically recalled and workflow is stopped before the document is deleted.

path Parameters
packageId
required
integer <int64>

Package ID of the package which contains the document.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Get Workflow Users For Enterprise Package

Business applications can use this service API to get a list of users in the workflow.

path Parameters
packageId
required
integer <int64>

The ID of the document for which the recipients are to be requested.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Workflow User of Enterprise Package

Business applications can use this service API to update the details of a recipient, group or place holder who has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications wants to override the details of a specific user within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow recipient is identified by the order at which it is added to the workflow. Note, while XML type document preparation, only supports role types "SIGNER", "REVIEWER" and "CARBON_COPY".

path Parameters
packageId
required
integer <int64>

The package ID for which workflow user needs to be updated.

order
required
integer <int32>

The order of the user in workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

The email address of the new user to be updated in workflow. If no value is provided, old value will be retained.

user_name
string

Name of the recipient to be updated. If no value is provided, old value will be retained.

email_notification
boolean

Setting its value to "true" sends an email notification to the user when its turn arrives in workflow. Setting its value to "false" does not send the email notification to the user on its turn. If no value is provided, old value will be retained.

mobile_number
string
role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

email_language_code
string

email language code

Responses

Request samples

Content type
{
  • "user_email": "string",
  • "user_name": "string",
  • "email_notification": true,
  • "mobile_number": "string",
  • "role": "SIGNER",
  • "signing_order": 0,
  • "email_language_code": "string"
}

Response samples

Content type
application/json
{
  • "user_email": "string",
  • "signing_order": 0,
  • "guest_user": true,
  • "email_language_code": "string"
}

Update Placeholder of Enterprise Package

Business applications can use this service API to update a placeholder in the workflow. Normally this call is useful after a template has been applied to a document and business applications wants to override the details of a specific place holder within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow place holder is identified by the order at which it is added to the workflow. While XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY".

path Parameters
packageId
required
integer <int64>

ID of the package for which the placeholder is to be added.

order
required
integer <int32>

Order of the recipient in the workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
placeholder
string

The name of the new placeholder to be added in workflow. If no value is provided, old value will be retained.

email_notification
boolean

Setting its value to "true" sends an email notification to the user when its turn arrives in workflow. Setting its value to "false" does not send the email notification to the user on its turn. If no value is provided, old value will be retained.

role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

Responses

Request samples

Content type
{
  • "placeholder": "string",
  • "email_notification": true,
  • "role": "SIGNER",
  • "signing_order": 0
}

Response samples

Content type
application/json
{ }

Update Workflow Group of Enterprise Package

Business applications can use this service API to update the details of a group that has already been added to a workflow. Normally this call is useful after a template has been applied to a document and business applications wants to override the details of a specific group within the workflow. The ID of the workflow document is provided in the resource URL, and the workflow group is identified by the order at which it is added to the workflow. While XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"

path Parameters
packageId
required
integer <int64>

The package ID for which workflow group needs to be updated.

order
required
integer <int32>

The order of the user in workflow.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
group_name
string

The name of the group to be updated in workflow. If no value is provided, old value will be retained.

email_notification
boolean

Setting its value to "true" sends an email notification to the group members when their turn arrives in workflow. Setting its value to "false" does not send the email notification to the group members on their turn. If no value is provided, old value will be retained.

access_sms_otp
boolean
mobile_number
string
role
required
string
Enum: "SIGNER" "REVIEWER" "EDITOR" "INPERSON_HOST" "CARBON_COPY"
signing_order
integer <int32>

Order in which the workflow will be signed by the recipients. This signing order is important when workflow type is set to "CUSTOM".

Responses

Request samples

Content type
{
  • "group_name": "string",
  • "email_notification": true,
  • "access_sms_otp": true,
  • "mobile_number": "string",
  • "role": "SIGNER",
  • "signing_order": 0
}

Response samples

Content type
application/json
{ }

Complete Enterprise Package in the Middle (Terminate Workflow)

Business applications can mark the workflow completed even in the middle of the workflow. Use this service API to change the status of the workflow to completed. If there are recipients who have not signed the document yet. Their signature will not be required any more and they will not be able to see the document in their inbox any further.

Bearer token should belong to document owner or enterprise admin can use scope variable to get the access token on behalf of document owner to perform this action.

path Parameters
packageId
required
integer <int64>

The package ID from which the recipient is to be deleted.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Account Management

This section entails the web services for the Account Management i.e. Register User, Set or Reset Password, Get Role etc.

Get Account Invitations

Business applications can use this service API to get a list of invitations from different enterprises.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
string

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Accept Account Invitation

Business applications can use this service API to accept an invitation and reject all the other invitations.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
enterprise_name
required
string non-empty

Name of the enterprise whose invitation is to be accepted.

Responses

Request samples

Content type
{
  • "enterprise_name": "string"
}

Response samples

Content type
application/json
{ }

Reject All Account Invitations

Business applications can use this service API to reject all the invitations from different accounts.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Register User (Free Trial)

Business applications can use this service API to register a new user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_name
required
string non-empty

Name of user that is to be registered.

user_email
required
string non-empty

Email Address of the user to be registered.

job_title
string

Job title of the user. (Optional)

company_name
string

Company name for the user. (Optional)

mobile_number
string

Mobile number of the user. (Optional)

country
string

Country name for the user. All values in the appendix - Country list are accepted. (Optional)

time_zone
string

Timezone name for the user. All values in the appendix - Timezone list are accepted. (Optional)

language
string

Language selected for the user. All values in the appendix - Language list are accepted. (Optional)

object

Name of the enterprise from where the invitation is sent. In case user is accepting an invitation from an enterprise. (Optional)

service_agreements
required
boolean

service agreements user consent for account registration.

user_csp_id
string
user_ra_id
string
marketing_emails
required
boolean

To receive promotional emails against marketing campaign, this must be set to true.

Responses

Request samples

Content type
{
  • "user_name": "string",
  • "user_email": "string",
  • "job_title": "string",
  • "company_name": "string",
  • "mobile_number": "string",
  • "country": "string",
  • "time_zone": "string",
  • "language": "string",
  • "invitation": {
    },
  • "service_agreements": true,
  • "user_csp_id": "string",
  • "user_ra_id": "string",
  • "marketing_emails": true
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

Get Account

Business applications can use this service API to get the account information of a logged in user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "user_email": "string",
  • "user_name": "string",
  • "created_on": "string",
  • "enabled": true,
  • "fonts": [
    ],
  • "service_plan": {
    },
  • "enterprise": {
    }
}

Resend Activation Email

Business applications can use this service API to resend the activation email.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email address of user that is to be activated.

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{ }

Add Feedback

Business applications can use this service API to request feedback from a user who had just deleted their account. Feedback could be used by the business to determine areas of improvements, and help determine the reason for account deletion.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
feedBack
string
q
string

Responses

Request samples

Content type
{
  • "feedBack": "string",
  • "q": "string"
}

Response samples

Content type
application/json
{ }

Reset Password

This API is specifically used by business applications to reset their account passwords. Access token can be used to reset password for a user.Authentication API will return new access token and refresh token in response when password is reset. Further API calls should be made using this new access/refresh token as previous access/refresh tokens are expired

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
security_answer
string
user_new_password
string
user_email
string

Responses

Request samples

Content type
{
  • "security_answer": "string",
  • "user_new_password": "string",
  • "user_email": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Send Forgot Password Request

Business applications can use this service API to send an email with instructions to reset a user’s password.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email address of user for which the forget password request is to be sent.

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{ }

Set New Password

This API is specifically used by business applications to change their account passwords. SigningHub requires a business application to change password on the following events:

  1. Password Expiry - When the account password has expired after a predefined time duration, i.e. as configured in their password policy.

  2. Enforce Password Change on First Login - When this option is configured in their password policy.

Access token can be used to set a new password for a user.Authentication API call will return access token in x-change-password response header when password reset required.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The one time access token obtained in "x-change-pasword" response header of Authentication API

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
security_question
required
string non-empty

Security question that is to be set.

security_answer
required
string non-empty

Security answer that is to be set.

password
required
string non-empty

Password of the user that is to be set.

q
string

Responses

Request samples

Content type
{
  • "security_question": "string",
  • "security_answer": "string",
  • "password": "string",
  • "q": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Account Usage Statistics

Business applications can use this service API to get the account usage statistics.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "storage": {
    },
  • "signature": {
    },
  • "workflow": {
    },
  • "template": {
    },
  • "user": {
    }
}

Documents Statistics

Business applications can use this service API to get the documents count with respect to their statuses.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-source
string
Example: Library

This is the identification of the source of the document from where the document is uploaded, e.g. "My App".

Responses

Response samples

Content type
application/json
{
  • "draft": 0,
  • "pending": 0,
  • "shared": 0,
  • "signed": 0,
  • "approved": 0,
  • "declined": 0,
  • "completed": 0,
  • "updated": 0,
  • "archived": 0
}

Get Account Password Policy

Business applications can use this service API to get the password policy for the account of a logged in user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{
  • "number": true,
  • "special_character": true,
  • "upper_case": true,
  • "minimum_length": 0
}

Get User Role

Business applications can use this service API to get the enterprise role and list of features of the application allowed by the enterprise admin.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
string
Default: true

True if response should have images in base64 format. False will only return the resource URLs in response.

Responses

Response samples

Content type
application/json
{
  • "role_name": "string",
  • "access_control": {
    },
  • "user_setting": {
    },
  • "enterprise_setting": {
    }
}

Get User Activity Log Details

Business applications can use this service API to get the details of an action performed by the user. The action is identified by the log_id provided in the resource URL.

path Parameters
logId
required
integer <int64>

The ID of the log action for which the details are requested.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
string
Default: true

True if response should have images in base64 format. False will only return the resource URLs in response.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "key": "string",
  • "key_label": "string",
  • "value": "string",
  • "value_label": "string",
  • "visible": true,
  • "order": 0,
  • "certificate_base64": "string",
  • "certification_base64_url": "string",
  • "type": "string"
}

Get User Activity Logs

Business applications can use this service API to get the list of actions performed by a user.

path Parameters
pageNo
required
integer <int32>

Page number, according the division of records per page.

recordsPerPage
required
integer <int32>

Number of records that are needed to be fetched in one request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Identity for a User

SigningHub application relies on email addresses of the user to uniquely identify them as a user. If client system do not want the email address to be used frequently, they can attach another identity to the user using the following API.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email of the user for whom another identity is provided.

name
string

Authentication profile name

key
required
string non-empty

A key name stored in the database to be used as an identity. It can be another email address, user Id, Certificate Id, RUT, VO_ID, UNIQUE_NO etc

value
required
string non-empty

Value of the identity key stored in the database which later can be used to verify the user while authentication.

Responses

Request samples

Content type
{
  • "user_email": "string",
  • "name": "string",
  • "key": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{ }

Get Notifications

Business applications can use this service API to get the notifications of logged in user.

path Parameters
recordPerPage
required
integer <int32>

Total records for a page to be retrieved.

pageNo
required
integer <int32>

Number of page to be retrieved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-total-records
string
Default: 212

Total number of records found with the provided search criteria.

x-unread-records
string
Default: 3

Number of unread notifications so far.

Responses

Response samples

Content type
application/json
{
  • "user_email": "string",
  • "user_name": "string",
  • "notifications": [
    ]
}

Device Registration for Push Notification

This API can be used for registering mobile devices for sending push notifications.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
device_token
required
string non-empty

Token generated by the mobile apps. This token is used why sending push notifications from Google's Firebase Cloud Messaging.

os_type
required
string non-empty

Operating system that will handle the push notifications. Possible values are IOS and ANDROID.

Responses

Request samples

Content type
{
  • "device_token": "string",
  • "os_type": "string"
}

Response samples

Content type
application/json
{ }

Personal Settings

This section entails the web services for managing the settings of personal users i.e. Groups, Contact, Templates etc.

Get Groups

Business applications can use this service API to get the list of groups for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

It is possible to search based upon the criterion supplied under the "x-search-text" header.Furthermore, it is possible to search a user's personal groups or that of the enterprise to which the user belongs.

The response contains both the group name and the members thereof.Group member details returned are email address and user name.

path Parameters
recordPerPage
required
integer <int32>

Total number of records to be retrieved in a page.

pageNo
required
integer <int32>

Page number to be retrieved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: U2FsZXM=

Search text if required. This is optional and without it the entire list is returned.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-enterprise
string
Default: true

If set as "true" only enterprise groups list will be returned. In case of "false"only the user's groups list will be returned.If you do not set the header, then both enterprise and user's groups lists will be returned.

x-total-records
string
Example: 10

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Library Documents

Business applications can use this service API to retieve documents from both personal and enterprise libraries for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

It is possible to search based upon the criterion supplied under the "x-search-text" header.Furthermore, it is possible to search a user's personal library or that of the enterprise to which the user belongs.

path Parameters
recordPerPage
required
integer <int32>

Total number of records to be retrieved in a page.

pageNo
required
integer <int32>

Page number to be retrieved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: c2FsZXMgY29udHJhY3QgMTA1

Search text if required. This is optional and without it the entire list is returned.
Search text sent in headers for further filtration of the documents.Document id, name and template name can be searched.Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-enterprise
string
Default: true

Set to "true" to search the entire enterprise contact list. Otherwise, "false" to search only the user's contact list.

x-total-records
string
Example: 10

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Change Password

Business applications can use this service API to change the password of the current user. This means the enterprise administrator or the enterprise user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_old_password
required
string non-empty

Old password of the user.

user_new_password
required
string non-empty

New password of the user.

Responses

Request samples

Content type
{
  • "user_old_password": "string",
  • "user_new_password": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string"
}

Get Signature Delegation Settings

Business applications can use this service API to get delegation settings of logged in user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "delegate": [
    ]
}

Update Signature Delegation Settings

Business applications can use this service API to update the signature delegation settings of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

Signature delegation allows a user to delegate any requested signing operation for them to another user. The API call requires not only the identifier and name of the individual to whom delegation is given but also the period via start and end date, when the delegation applies.

The designated user must have a SigningHub account.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
enabled
required
boolean

Set to "true" to enable delegate signing to another user, or "false" to remove a previously set permission. If enabling delegated signing all other parameters are mandatory.

Array of objects (DelegateRequest)

Responses

Request samples

Content type
{
  • "enabled": true,
  • "delegate": [
    ]
}

Response samples

Content type
application/json
{ }

Get General Profile Information

Business applications can use this service API to get the general profile information of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "general": {
    },
  • "security": {
    },
  • "locale": {
    },
  • "enterprise": {
    }
}

Get Profile Picture (Base64)

Business applications can use this service API to get profile picture of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "photo": "string"
}

Update Profile Picture

Business applications can use this service API to update profile picture of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
photo
string

Base64 encoded string of image to be updated as profile picture.

Responses

Request samples

Content type
{
  • "photo": "string"
}

Response samples

Content type
application/json
{ }

Get Hand Signature Text For Web

Business application can get the hand signature appearance used for upload option on web browsers.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Initials For Upload Option

Business application can get the initials appearance used for upload option.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Hand Signature Upload For Mobile

Business application can get the hand signature appearance used for upload option on mobile apps and browsers.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Hand Signature Upload For Web

Business application can get the hand signature appearance used for upload option on web browsers.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Signature Settings

Business applications can use this service API to get the signature settings for the current user. This means the enterprise administrator or the enterprise user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
string
Default: true

True if response should have images in base64 format. False will only return the resource URLs in response.

Responses

Response samples

Content type
application/json
{
  • "signature": {
    },
  • "appearance": {
    }
}

Get Initials For Text Option

Business application can get the initials appearance used for text option.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Hand Signature Text For Mobile

Business application can get the hand signature appearance used for text option on mobile apps and browsers.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Templates

Business applications can use this service API to get list of templates for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

It is possible to search based upon the criterion supplied under the "x-search-text" header.Furthermore, it is possible to search a user's personal templates or the enterprise templates as allowed against their user role by their enterprise admin.

path Parameters
recordPerPage
required
integer <int32>

Total number of records to be retrieved in a page.

pageNo
required
integer <int32>

Page number to be retrieved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: TXkgdGVtcGxhdGU=

Search text if required. This is optional and without it the entire list is returned.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-enterprise
string
Default: true

When set as "true" only enterprise templates list will be returned. In case of "false"only the user's templates list will be returned.If you do not set the header, then both enterprise and user's templates lists will be returned.

x-total-records
string
Example: 10

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Profile Picture

Business applications can use this service API to get profile picture of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Signature Appearance

Business application can get the hand signature preview image file using the following API endpoint.

path Parameters
appearanceName
required
string
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Reset User Emails To Default

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Update General Profile Information

Business applications can use this service API to update general profile information of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_name
required
string non-empty

Name of the user whose information requires updating. This is a mandatory field and must match the user name for whom the access token was granted to.

job_title
string

Job title of the user.

company_name
string

Company name for the user.

mobile_number
string

Mobile number of the user. Remember to include the international dialing and country codes. For example, UK numbers require 00 44 to proceed the actual mobile number. The leading zero must be dropped from the mobile number also, and replaced with the international and country dialing codes.

country
string

Country name for the user. All values in the appendix - Country list are accepted.

time_zone
string

Timezone name for the user. All values in the appendix - Timezone list are accepted.

language
string

Language selected for the user. All values in the appendix - Language list are accepted.

user_national_id
string

National identity number of the user.

Responses

Request samples

Content type
{
  • "user_name": "string",
  • "job_title": "string",
  • "company_name": "string",
  • "mobile_number": "string",
  • "country": "string",
  • "time_zone": "string",
  • "language": "string",
  • "user_national_id": "string"
}

Response samples

Content type
application/json
{ }

Update Locale Settings

Business applications can use this service API to update locale profile information of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
country
string

Country name to be set for the user. All values in the appendix - Country List are accepted. If no value is provided, previous value will be retained.

timezone
string

Standard string for timezone information. All values in the appendix - Timezone List are accepted. If no value is provided, previous value will be retained.

language
string

Language selected for the user. All values in the appendix - Language list are accepted. If no value is provided, previous value will be retained.

Responses

Request samples

Content type
{
  • "country": "string",
  • "timezone": "string",
  • "language": "string"
}

Response samples

Content type
application/json
{ }

Update Security Settings

Business applications can use this service API to update profile’s security information of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
password
required
string non-empty

Password of the user used for the authentication.

question
required
string non-empty

New security question to be set for the user.

answer
required
string non-empty

New security answer to be set for the user.

Responses

Request samples

Content type
{
  • "password": "string",
  • "question": "string",
  • "answer": "string"
}

Response samples

Content type
application/json
{ }

Update Initial Appearance

Business applications can use this service API to update the signature appearance when initialling a document of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
default_method
required
string
Enum: "DRAW" "UPLOAD" "TEXT"
upload_image
string

Base64 encoded string of the image that contains the captured handwritten signature image.

text_value
string

Text value to save against the new saved image under user settings.

Responses

Request samples

Content type
{
  • "default_method": "DRAW",
  • "upload_image": "string",
  • "text_value": "string"
}

Response samples

Content type
application/json
{ }

Update Hand Signature (Browser)

Business applications can use this service API to update the signature appearance setting used in web browsers for the current user. This means the enterprise administrator or the enterprise user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
default_method
required
string
Enum: "DRAW" "UPLOAD" "TEXT"
upload_image
string

Base64 encoded string of the image that contains the captured handwritten signature image.

text_value
string

Text value to save against the new saved image under user settings.

Responses

Request samples

Content type
{
  • "default_method": "DRAW",
  • "upload_image": "string",
  • "text_value": "string"
}

Response samples

Content type
application/json
{ }

Update Signature Appearance Design

Business applications can use this service API to update signature appearance design for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

The signature appearance design defines the content of the visible signature appearance.Choices are hand signature only, hand signature with details, or hand signature with details and company logo/image.In this case "details" is defined as the "signed by", "signing time" and signing reason" fields.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
default_design
string

New design name to be updated for the signature design appearance .

Responses

Request samples

Content type
{
  • "default_design": "string"
}

Response samples

Content type
application/json
{ }

Update Hand Signature (Mobile)

Business applications can use this service API to update the signature appearance setting used in mobile browsers for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
default_method
required
string
Enum: "DRAW" "UPLOAD" "TEXT"
upload_image
string

Base64 encoded string of the image that contains the captured handwritten signature image.

text_value
string

Text value to save against the new saved image under user settings.

Responses

Request samples

Content type
{
  • "default_method": "DRAW",
  • "upload_image": "string",
  • "text_value": "string"
}

Response samples

Content type
application/json
{ }

Update Signature Settings Metadata

Business applications can use this service API to update signature settings metadata of the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request. The metadata comprises three fields; namely signing reason, signing location and contact information of the signer, which together are optional fields for visible signature appearance under the ETSI PAdES Signature Profile standards.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
signing_reason
string

String value for signing reason to be updated.

contact_information
string

String value for contact information to be updated.

signing_location
string

String value for signing location to be updated.

Responses

Request samples

Content type
{
  • "signing_reason": "string",
  • "contact_information": "string",
  • "signing_location": "string"
}

Response samples

Content type
application/json
{ }

Remove Account Request

Business applications can use this service API to request the deletion of an account. This API will trigger the account deletion confirmation email against the requested user. For an enterprise account, all the enterprise users, except the enterprise owner, with in the account must be deleted first.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Remove Account

Business applications can use this service API to delete an account against which a "Remove Account Request" service API was initiated, and the user authorized the account deletion.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
q
required
string non-empty

Responses

Request samples

Content type
{
  • "q": "string"
}

Response samples

Content type
application/json
{ }

Get Personal Legal Notice

Business applications can use this service API to get a personal Legal Notice for Users. An admin who has permissions to manage Legal Notices in his role, can get legal notices. The role dictates things such as allowed Read legal notice available to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "content": "string"
}

Update Personal Legal Notice

Business applications can use this service API to edit a personal Legal Notice for Users. An admin who has permissions to manage Legal Notices in his role, can edit legal notices. The role dictates things such as allowed Edit legal notice available to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
title
required
string [ 1 .. 255 ] characters

Legal Notice Title

content
required
string non-empty

Legal Notice Content

Responses

Request samples

Content type
{
  • "title": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{ }

Delete Personal Legal Notice

Business applications can use this service API to delete a personal Legal Notice for Users. An admin who has permissions to manage Legal Notices in his role, can delete legal notices. The role dictates things such as allowed Delete legal notice available to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Add Personal Legal Notice

Business applications can use this service API to add a personal Legal Notice for Users. An admin who has permissions to manage Legal Notices in his role, can add new legal notices. The role dictates things such as allowed Add legal notice available to the user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
title
required
string [ 1 .. 255 ] characters

Legal Notice Title

content
required
string non-empty

Legal Notice Content

Responses

Request samples

Content type
{
  • "title": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "id": 0
}

Add Personal Group

Business applications can use this service API to add a personal group for Users. A group admin who has permissions to manage group in this role, can add new groups.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Name
required
string [ 1 .. 255 ] characters

Group Name

Description
string

Group Description

required
Array of objects (GroupMembers)

Responses

Request samples

Content type
{
  • "Name": "string",
  • "Description": "string",
  • "Members": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string"
}

Update Personal Group

Business applications can use this service API to update personal group information for users. A group Admin who has permissions to manage groups in this role, can update personal groups.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
Name
required
string [ 1 .. 255 ] characters

Group Name

Description
string

Group Description

required
Array of objects (GroupMembers)

Responses

Request samples

Content type
{
  • "Name": "string",
  • "Description": "string",
  • "Members": [
    ]
}

Response samples

Content type
application/json
{ }

Delete Personal Group

Business applications can use this service API to delete personal group for its users. A group admin who has permissions to manage users in his role, can delete groups for user. The Role dictates things such as allowed delete groups available to the user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{ }

Get Personal Group

Business applications can use this service API to get personal group for its users. A group admin who has permissions to manage users in this role, can get personal groups for user.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "members": [
    ]
}

Get Legal Notices

Business applications can use this service API to get the list of legal notices for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

path Parameters
recordPerPage
required
integer <int32>

Total number of records to be retrieved in a page.

pageNo
required
integer <int32>

Page number to be retrieved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of successful authentication via "Password" or "Scope". If "Scope Authentication" was used, then this service will be performed for the user on behalf of the business application.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: U2FsZXM=

Search text if required. This is optional and without it the entire list is returned.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-enterprise
string
Default: true

If set as "true" only enterprise legal notices list will be returned. In case of "false"only the user's legal notices list will be returned.If you do not set the header, then both enterprise and user's legal notices lists will be returned.

x-total-records
string
Example: 10

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Contacts

Business applications can use this service API to get a list of contacts for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

It is possible to search based upon the criterion supplied under the "x-search-text" header.Furthermore, it is possible to search a user's specific contacts or that of the enterprise to which the user belongs.

The search response information contains the user email address and respective user name.

path Parameters
recordPerPage
required
integer <int32>

Total number of records to be retrieved in a page.

pageNo
required
integer <int32>

Page number to be retrieved.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-search-text
string
Example: am9obg==

Search text if required. This is optional and without it the entire list is returned.
Furthermore, recommended value for search text parameter is in Base64 encoded format.

x-enterprise
string
Default: true

When set as "true" only enterprise contacts list will be returned. In case of "false"only the user's contacts list will be returned.If you do not set the header, then both enterprise and user's contacts lists will be returned.

x-total-records
string
Example: 10

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Contact

Business applications can use this service API to add a contact for the current user. This means the enterprise administrator or the enterpriser user if the "scope" variable was used in the authentication request.

A contact does not require a SigningHub account and is an easy way of managing document recipients.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_name
required
string non-empty

User name of the user to be added as a contact.

user_email
required
string non-empty

Email address of the user to be added as a contact.

Responses

Request samples

Content type
{
  • "user_name": "string",
  • "user_email": "string"
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

General

This section entails the web services for managing the general operations i.e. About, System Settings, and Branding.

OTP Verification

Business applications can use this service API to verify an OTP, generated using OTP Login Authentication.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-otp
string
Default: 456789

OTP that is generated and sent to the user's mobile.

Responses

Response samples

Content type
application/json
{ }

Get Profile Picture of Recipient

Business application can get the profile picture of a recipient that has signed the document.

path Parameters
encryptKey
required
string

Encrypted string used to identify the recipient for which the photo is requested.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

About SigningHub

Business applications can use this service API to get the SigningHub version and build information.

header Parameters
Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "installation_name": "string",
  • "version": "string",
  • "build": "string",
  • "patents": {
    },
  • "copyright": "string"
}

System Settings

Business applications can use this service API to get the system settings of a logged in enterprise user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "installation_name": "string",
  • "installation_type": "string",
  • "web_address": "string",
  • "api_address": "string",
  • "create_account_webpage": "string",
  • "privacy_policy_webpage": "string",
  • "term_of_services_webpage": "string",
  • "agree_privacy_policy_and_terms_of_service": true,
  • "default_country": "string",
  • "allow_changing_country": true,
  • "default_timezone": "string",
  • "allow_changing_timezone": true,
  • "default_language": "string",
  • "password_policy": {
    },
  • "signature_types": {
    },
  • "support_email": "string",
  • "system_error_email": "string",
  • "mobile_apps_url": "string",
  • "session_timeout": 0,
  • "company_name": "string",
  • "allow_changing_language": true,
  • "allow_national_id": true,
  • "google_analytics_mobile_web": "string",
  • "bing_analytics_mobile_web": "string",
  • "error_notification_timeout": 0,
  • "allow_marketing_emails": true,
  • "hide_edit_signature_dialog": true,
  • "billing": {
    }
}

Get SigningHub Admin Branding

Retrieve the default branding of SigningHub Application as set by the SigningHub administrator via the administration console. This includes the logo, favicon and colours that comprise the branding options. Note this is not to be confused with the Enterprise level branding. For these settings click here.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-base64
string
Default: true

Responses

Response samples

Content type
application/json
{
  • "logo": "string",
  • "logo_url": "string",
  • "favicon": "string",
  • "favicon_url": "string",
  • "colors": {
    }
}

Get SH Admin Branding Favicon

Business application can get the application favicon configured in the application's admin console branding.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "client_credentials" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
"string"

Get Languages

Business applications can use this service API to get the supported languages

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained as a result of successful authentication via "password" grant type.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json

Responses

Response samples

Content type
application/json
{
  • "default_language": "string",
  • "allow_changing_language": true,
  • "supported_languages": {
    }
}

SigningHub Admin APIs

This section covers administration of enterprise accounts in SigningHub.

The API level is above that used in other sections in that this allows a SigningHub Administrator to create an Enterprise within SigningHub and hence a SigningHub Enterprise Administrator for the new Enterprise.

These APIs are strictly for SigningHub System Administrators, who have been issued a client TLS certificate for Admin Console access.

Admin Authentication

This API can be used to authenticate to SigningHub Administration.It requires a current, valid SigningHub Administration client TLS certificate.

The API call should present a client TLS certificate in the HTTPS call.

Note the password option is optional.The use of these is controlled by SigningHub Administration settings.

header Parameters
Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-password
string
Default: Password

Password of SigningHub Administrator if required.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

Create Account

Applications can call this API to create Individual Users as well as Enterprise Administrators and associated accounts. Only SigningHub Administrators have permission to create new Individual User accounts, Enterprise and thus Enterprise Administrator accounts, and use this API. To create Enterprise Users use the Register Enterprise User API.

Using this API will create a new Individual User, Enterprise in SigningHub, and the first Enterprise Admin for this Enterprise.

You must authenticate using your SigningHub Administration client TLS certificate as described here, in order to use this and other SigningHub Admin APIs.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

OAuth access token obtained after a successful authentication. This service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the user management privileges.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_name
required
string non-empty

Name of the new SigningHub user.

user_email
required
string non-empty

Email address of the new SigningHub user.

enterprise_name
string

Name of the enterprise for the new account. If omitted a random enterprise name will be generated by SigningHub. The enterprise name is mandatory when creating enterprise accounts using enterprise service plans.

job_title
string

Job title of the new SigningHub user.

company_name
string

Company name of the new SigningHub user.

mobile_number
string

Mobile number of the new SigningHub user.

service_plan
required
string non-empty

Specifies the Service Plan to be used for this account.

notifications
boolean

This defines whether registered user would get an email notification about the account creation. Default value is 'false'.

user_password
string

The password of the user account. This is optional if you want your users to authenticate externally e.g. via SAML, Salesforce, Office 365 etc. rather than using a SigningHub ID (email/password). If password is provided, application expects the security question and answer as mandatory fields.

security_question
string

Security question used to reset password if user forgets his password. This is mandatory if you wish to allow the user to sign without manually, via an email link, completing the registration process. If security question is provided, application expects the password and security answer as mandatory fields.

security_answer
string

Security answer used to reset the password if user forgets his password. This is mandatory if you wish to allow the user to sign without manually, via an email link, completing the registration process. If security answer is provided, application expects the password and security question as mandatory fields.

service_agreements
required
boolean

User consent terms of service and privacy policies for account registration.

Responses

Request samples

Content type
{
  • "user_name": "string",
  • "user_email": "string",
  • "enterprise_name": "string",
  • "job_title": "string",
  • "company_name": "string",
  • "mobile_number": "string",
  • "service_plan": "string",
  • "notifications": true,
  • "user_password": "string",
  • "security_question": "string",
  • "security_answer": "string",
  • "service_agreements": true
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

Change User Service Plan

Applications can call this API update a user's service plan. This requires SigningHub Administrator permission.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

Oauth access token of the logged in user. This must be a SigningHub Administrator who has the rights to create an account.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email address of the account owner.

service_plan
required
string non-empty

New Service Plan name, which is to be assigned to the user.

Responses

Request samples

Content type
{
  • "user_email": "string",
  • "service_plan": "string"
}

Response samples

Content type
application/json
{ }

Get Accounts

API is used to get accounts and filter them based on the search criteria.

path Parameters
pageNo
required
integer <int32>

Page number, according the division of records per page.

recordsPerPage
required
integer <int32>

Number of records that are needed to be fetched in one request.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

Oauth access token of the logged in user. This must be a SigningHub Administrator who has the rights to create an account.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
x-user-name
string
Default: John Doe

Name of the account user to be searched

x-user-email
string
Default: john.doe@ascertia.com

Email of the account user to be searched.

x-enterprise-name
string
Default: Ascertia

Name of enterprise by which the account is to be searched.

x-billing-mode
string
Default: ONLINE

Billing mode for the account, possible values are ONLINE, OFFLINE. If developers intend to ignore billing mode, it's optional.

x-payment-type
string
Default: PAY_REGULARLY

Payment type for the account search, possible values are PAY_REGULARLY, PAY_AS_YOU_GO.

x-service-plan
string
Default: Basic Individual

Name of service plan to search

x-activated
string
Default: True

True, if accounts are activated.

x-enabled
string
Default: True

True, if accounts are enabled.

x-from
string
Default: 2017-05-01

Date value in 8601 format from where the account is to be searched.

x-to
string
Default: 2017-05-22

Date value in 8601 format to which the account is to be searched.

x-total-records
string
Default: 212

Total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
{
  • "user_name": "string",
  • "user_email": "string",
  • "service_plan": "string",
  • "enterprise_id": 0,
  • "enterprise_name": "string",
  • "created_on": "string"
}

Service Plan Reset

Business applications can use this API to reset the Service Plan statistics for a user. Every user in SigningHub has an associated Service Plan. Within this the number of signatures, workflows, templates, etc., are recorded. This API call allows the calling application to reset these statistics for the given user.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

Oauth access token of the logged in user. This must be a SigningHub Administrator who has the rights to create an account.

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
user_email
required
string non-empty

Email of the user whose statistics are to be reset.

Responses

Request samples

Content type
{
  • "user_email": "string"
}

Response samples

Content type
application/json
{ }

Appendix

Country List

The key/value pairs for country references that SigningHub recognizes.  These are used in various API calls.

  "Afghanistan": "Afghanistan",
  "AlandIslands": "AlandIslands",
  "Albania": "Albania",
  "Algeria": "Algeria",
  "American Samoa": "American Samoa",
  "Andorra": "Andorra",
  "Angola": "Angola",
  "Anguilla": "Anguilla",
  "Antarctica": "Antarctica",
  "Antigua and Barbuda": "Antigua and Barbuda",
  "Argentina": "Argentina",
  "Armenia": "Armenia",
  "Aruba": "Aruba",
  "Australia": "Australia",
  "Austria": "Austria",
  "Azerbaijan": "Azerbaijan",
  "Bahamas": "Bahamas",
  "Bahrain": "Bahrain",
  "Bangladesh": "Bangladesh",
  "Barbados": "Barbados",
  "Belarus": "Belarus",
  "Belgium": "Belgium",
  "Belize": "Belize",
  "Benin": "Benin",
  "Bermuda": "Bermuda",
  "Bouvet Island": "Bouvet Island",
  "Bhutan": "Bhutan",
  "Bolivia": "Bolivia",
  "Bosnia and Herzegovina": "Bosnia and Herzegovina",
  "Botswana": "Botswana",
  "Brazil": "Brazil",
  "British Indian Ocean Territory": "British Indian Ocean Territory",
  "British Virgin Islands": "British Virgin Islands",
  "Brunei": "Brunei",
  "Bulgaria": "Bulgaria",
  "Burkina Faso": "Burkina Faso",
  "Burundi": "Burundi",
  "Cambodia": "Cambodia",
  "Cameroon": "Cameroon",
  "Canada": "Canada",
  "Cape Verde": "Cape Verde",
  "Cayman Islands": "Cayman Islands",
  "Central African Republic": "Central African Republic",
  "Chad": "Chad",
  "Chile": "Chile",
  "China": "China",
  "Christmas Island": "Christmas Island",
  "Cocos-Keeling-Islands": "Cocos-Keeling-Islands",
  "Colombia": "Colombia",
  "Comoros": "Comoros",
  "Congo": "Congo",
  "Cook Islands": "Cook Islands",
  "Costa Rica": "Costa Rica",
  "Croatia": "Croatia",
  "Cuba": "Cuba",
  "Cyprus": "Cyprus",
  "Czech Republic": "Czech Republic",
  "Denmark": "Denmark",
  "Democratic Republic of Congo": "Democratic Republic of Congo",
  "Djibouti": "Djibouti",
  "Dominica": "Dominica",
  "Dominican Republic": "Dominican Republic",
  "East Timor": "East Timor",
  "Ecuador": "Ecuador",
  "Egypt": "Egypt",
  "El Salvador": "El Salvador",
  "Equatorial Guinea": "Equatorial Guinea",
  "Eritrea": "Eritrea",
  "Estonia": "Estonia",
  "Ethiopia": "Ethiopia",
  "Falkland Islands": "Falkland Islands",
  "Faroe Islands": "Faroe Islands",
  "Federated States of Micronesia": "Federated States of Micronesia",
  "Fiji": "Fiji",
  "Finland": "Finland",
  "France": "France",
  "French Guiana": "French Guiana",
  "French Polynesia": "French Polynesia",
  "French Southern and Antarctic Lands": "French Southern and Antarctic Lands",
  "Gabon": "Gabon",
  "Gambia": "Gambia",
  "Georgia": "Georgia",
  "Germany": "Germany",
  "Ghana": "Ghana",
  "Gibraltar": "Gibraltar",
  "Greece": "Greece",
  "Greenland": "Greenland",
  "Grenada": "Grenada",
  "Guadeloupe": "Guadeloupe",
  "Guam": "Guam",
  "Guatemala": "Guatemala",
  "Guernsey": "Guernsey",
  "Guinea": "Guinea",
  "Guinea-Bissau": "Guinea-Bissau",
  "Guyana": "Guyana",
  "HeardIs land and Mcdonald Islands": "HeardIs land and Mcdonald Islands",
  "Haiti": "Haiti",
  "Honduras": "Honduras",
  "Hong Kong": "Hong Kong",
  "Hungary": "Hungary",
  "Iceland": "Iceland",
  "India": "India",
  "Indonesia": "Indonesia",
  "Iran": "Iran",
  "Iraq": "Iraq",
  "Ireland": "Ireland",
  "Isle of Man": "Isle of Man",
  "Israel": "Israel",
  "Italy": "Italy",
  "CôtedIvoire": "CôtedIvoire",
  "Jamaica": "Jamaica",
  "Japan": "Japan",
  "Jersey": "Jersey",
  "Jordan": "Jordan",
  "Kazakhstan": "Kazakhstan",
  "Kenya": "Kenya",
  "Kiribati": "Kiribati",
  "Kuwait": "Kuwait",
  "Kyrgyzstan": "Kyrgyzstan",
  "Laos": "Laos",
  "Latvia": "Latvia",
  "Lebanon": "Lebanon",
  "Lesotho": "Lesotho",
  "Liberia": "Liberia",
  "Libya": "Libya",
  "Liechtenstein": "Liechtenstein",
  "Lithuania": "Lithuania",
  "Luxembourg": "Luxembourg",
  "Macau": "Macau",
  "Macedonia": "Macedonia",
  "Madagascar": "Madagascar",
  "Malawi": "Malawi",
  "Malaysia": "Malaysia",
  "Maldives": "Maldives",
  "Mali": "Mali",
  "Malta": "Malta",
  "Marshall Islands": "Marshall Islands",
  "Mauritania": "Mauritania",
  "Mauritius": "Mauritius",
  "Mayotte": "Mayotte",
  "Mexico": "Mexico",
  "Micronesia": "Micronesia",
  "Moldova": "Moldova",
  "Monaco": "Monaco",
  "Mongolia": "Mongolia",
  "Montenegro": "Montenegro",
  "Morocco": "Morocco",
  "Montserrat": "Montserrat",
  "Mozambique": "Mozambique",
  "Myanmar": "Myanmar",
  "Namibia": "Namibia",
  "Nauru": "Nauru",
  "Nepal": "Nepal",
  "Netherlands": "Netherlands",
  "Netherlands Antilles": "Netherlands Antilles",
  "New Caledonia": "New Caledonia",
  "New Zealand": "New Zealand",
  "Nicaragua": "Nicaragua",
  "Niger": "Niger",
  "Nigeria": "Nigeria",
  "Niue": "Niue",
  "Norfolk Island": "Norfolk Island",
  "Northern Mariana Islands": "Northern Mariana Islands",
  "North Korea": "North Korea",
  "Norway": "Norway",
  "Oman": "Oman",
  "Pakistan": "Pakistan",
  "Palau": "Palau",
  "Panama": "Panama",
  "Papua New Guinea": "Papua New Guinea",
  "Paraguay": "Paraguay",
  "Peru": "Peru",
  "Philippines": "Philippines",
  "Pitcairn Islands": "Pitcairn Islands",
  "Palestinian Occupied Territories": "Palestinian Occupied Territories",
  "Poland": "Poland",
  "Portugal": "Portugal",
  "Puerto Rico": "Puerto Rico",
  "Qatar": "Qatar",
  "Reunion": "Reunion",
  "Romania": "Romania",
  "Russia": "Russia",
  "Rwanda": "Rwanda",
  "Saint Barthélemy": "Saint Barthélemy",
  "Saint Kitts and Nevis": "Saint Kitts and Nevis",
  "Saint Lucia": "Saint Lucia",
  "Saint Vincent and the Grenadines": "Saint Vincent and the Grenadines",
  "Samoa": "Samoa",
  "San Marino": "San Marino",
  "São Tomé and Príncipe": "São Tomé and Príncipe",
  "Saudi Arabia": "Saudi Arabia",
  "Senegal": "Senegal",
  "Serbia": "Serbia",
  "Serbiaand Montenegro": "Serbiaand Montenegro",
  "Seychelles": "Seychelles",
  "Sierra Leone": "Sierra Leone",
  "Singapore": "Singapore",
  "Slovakia": "Slovakia",
  "Slovenia": "Slovenia",
  "Solomon Islands": "Solomon Islands",
  "Somalia": "Somalia",
  "South Africa": "South Africa",
  "South Korea": "South Korea",
  "Spain": "Spain",
  "Sri Lanka": "Sri Lanka",
  "Saint Helena Ascension and Tristanda Cunha": "Saint Helena Ascension and Tristanda Cunha",
  "Saint Pierre and Miquelon": "Saint Pierre and Miquelon",
  "Sudan": "Sudan",
  "Suriname": "Suriname",
  "Svalbard and Jan Mayen": "Svalbard and Jan Mayen",
  "Swaziland": "Swaziland",
  "Sweden": "Sweden",
  "Switzerland": "Switzerland",
  "Syria": "Syria",
  "Taiwan": "Taiwan",
  "Tajikistan": "Tajikistan",
  "Tanzania": "Tanzania",
  "Thailand": "Thailand",
  "Togo": "Togo",
  "Tokelau": "Tokelau",
  "Tonga": "Tonga",
  "Tunisia": "Tunisia",
  "Trinidad and Tobago": "Trinidad and Tobago",
  "Turkey": "Turkey",
  "Turkmenistan": "Turkmenistan",
  "Turks And Caicos Islands": "Turks And Caicos Islands",
  "Tuvalu": "Tuvalu",
  "United Arab Emirates": "United Arab Emirates",
  "Uganda": "Uganda",
  "United Kingdom": "United Kingdom",
  "Ukraine": "Ukraine",
  "Uruguay": "Uruguay",
  "United States": "United States",
  "US Virgin Islands": "US Virgin Islands",
  "Uzbekistan": "Uzbekistan",
  "Vanuatu": "Vanuatu",
  "Vatican City State": "Vatican City State",
  "Venezuela": "Venezuela",
  "Vietnam": "Vietnam",
  "Wallis and Futuna": "Wallis and Futuna",
  "Western Sahara": "Western Sahara",
  "Yemen": "Yemen",
  "Zambia": "Zambia",
  "Zimbabwe": "Zimbabwe"


Timezone List

The key/value pairs for time zones that SigningHub recognizes.  These are used in various API calls.

{
  "Dateline Standard Time": "(UTC-12:00) International Date Line West ",
  "Samoa Standard Time": "(UTC-11:00) Midway Island, Samoa",
  "Hawaiian Standard Time": "(UTC-10:00) Hawaii",
  "Alaskan Standard Time": "(UTC-09:00) Alaska",
  "Pacific Standard Time": "(UTC-08:00) Pacific Time (US & Canada)",
  "Pacific Standard Time (Mexico)": "(UTC-08:00) Tijuana, Baja California",
  "US Mountain Standard Time": "(UTC-07:00) Arizona",
  "Mountain Standard Time (Mexico)": "(UTC-07:00) Chihuahua, La Paz, Mazatlan",
  "Mountain Standard Time": "(UTC-07:00) Mountain Time (US & Canada)",
  "Central America Standard Time": "(UTC-06:00) Central America",
  "Central Standard Time": "(UTC-06:00) Central Time (US & Canada)",
  "Central Standard Time (Mexico)": "(UTC-06:00) Guadalajara, Mexico City, Monterrey",
  "Canada Central Standard Time": "(UTC-06:00) Saskatchewan",
  "SA Pacific Standard Time": "(UTC-05:00) Bogota, Lima, Quito",
  "Eastern Standard Time": "(UTC-05:00) Eastern Time (US & Canada)",
  "US Eastern Standard Time": "(UTC-05:00) Indiana (East)",
  "Venezuela Standard Time": "(UTC-04:30) Caracas",
  "Paraguay Standard Time": "(UTC-04:00) Asuncion",
  "Atlantic Standard Time": "(UTC-04:00) Atlantic Time (Canada)",
  "SA Western Standard Time": "(UTC-04:00) Georgetown, La Paz, San Juan",
  "Central Brazilian Standard Time": "(UTC-04:00) Manaus",
  "Pacific SA Standard Time": "(UTC-04:00) Santiago",
  "Newfoundland Standard Time": "(UTC-03:30) Newfoundland",
  "E. South America Standard Time": "(UTC-03:00) Brasilia",
  "Argentina Standard Time": "(UTC-03:00) Buenos Aires",
  "SA Eastern Standard Time": "(UTC-03:00) Cayenne",
  "Greenland Standard Time": "(UTC-03:00) Greenland",
  "Montevideo Standard Time": "(UTC-03:00) Montevideo",
  "Mid-Atlantic Standard Time": "(UTC-02:00) Mid-Atlantic",
  "Azores Standard Time": "(UTC-01:00) Azores",
  "Cabo Verde Standard Time": "(UTC-01:00) Cape Verde Is.",
  "Morocco Standard Time": "(UTC) Casablanca",
  "Coordinated Universal Time": "(UTC) Coordinated Universal Time",
  "GMT Standard Time": "(UTC) Dublin, Edinburgh, Lisbon, London, Saint Peter Port, Saint Helier",
  "Greenwich Standard Time": "(UTC) Monrovia, Reykjavik",
  "W. Europe Standard Time": "(UTC+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna",
  "Central Europe Standard Time": "(UTC+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague",
  "Romance Standard Time": "(UTC+01:00) Brussels, Copenhagen, Madrid, Paris",
  "Central European Standard Time": "(UTC+01:00) Sarajevo, Skopje, Warsaw, Zagreb",
  "W. Central Africa Standard Time": "(UTC+01:00) West Central Africa",
  "Jordan Standard Time": "(UTC+02:00) Amman",
  "GTB Standard Time": "(UTC+02:00) Athens, Bucharest, Istanbul",
  "Middle East Standard Time": "(UTC+02:00) Beirut",
  "Egypt Standard Time": "(UTC+02:00) Cairo",
  "South Africa Standard Time": "(UTC+02:00) Harare, Pretoria",
  "FLE Standard Time": "(UTC+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius",
  "Jerusalem Standard Time": "(UTC+02:00) Jerusalem",
  "E. Europe Standard Time": "(UTC+02:00) Minsk",
  "Namibia Standard Time": "(UTC+02:00) Windhoek",
  "Arabic Standard Time": "(UTC+03:00) Baghdad",
  "Arab Standard Time": "(UTC+03:00) Kuwait, Riyadh",
  "Russia TZ 2 Standard Time": "(UTC+03:00) Moscow, St. Petersburg, Volgograd",
  "E. Africa Standard Time": "(UTC+03:00) Nairobi",
  "Russia TZ 3 Standard Time": "(UTC+04:00) Izhevsk, Samara",
  "Georgian Standard Time": "(UTC+04:00) Tbilisi",
  "Iran Standard Time": "(UTC+03:30) Tehran",
  "Arabian Standard Time": "(UTC+04:00) Abu Dhabi, Muscat",
  "Azerbaijan Standard Time": "(UTC+04:00) Baku",
  "Mauritius Standard Time": "(UTC+04:00) Port Louis",
  "Caucasus Standard Time": "(UTC+04:00) Yerevan",
  "Afghanistan Standard Time": "(UTC+04:30) Kabul",
  "Russia TZ 4 Standard Time": "(UTC+05:00) Ekaterinburg",
  "Pakistan Standard Time": "(UTC+05:00) Islamabad, Karachi",
  "West Asia Standard Time": "(UTC+05:00) Tashkent",
  "India Standard Time": "(UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi",
  "Sri Lanka Standard Time": "(UTC+05:30) Sri Jayawardenepura",
  "Nepal Standard Time": "(UTC+05:45) Kathmandu",
  "Russia TZ 5 Standard Time": "(UTC+06:00) Almaty, Novosibirsk",
  "Central Asia Standard Time": "(UTC+06:00) Astana, Dhaka",
  "Myanmar Standard Time": "(UTC+06:30) Yangon (Rangoon)",
  "SE Asia Standard Time": "(UTC+07:00) Bangkok, Hanoi, Jakarta",
  "Russia TZ 6 Standard Time": "(UTC+07:00) Krasnoyarsk",
  "China Standard Time": "(UTC+08:00) Beijing, Chongqing, Hong Kong, Urumqi",
  "Russia TZ 7 Standard Time": "(UTC+08:00) Irkutsk, Ulaan Bataar",
  "Malay Peninsula Standard Time": "(UTC+08:00) Kuala Lumpur, Singapore",
  "W. Australia Standard Time": "(UTC+08:00) Perth",
  "Taipei Standard Time": "(UTC+08:00) Taipei",
  "Tokyo Standard Time": "(UTC+09:00) Osaka, Sapporo, Tokyo",
  "Korea Standard Time": "(UTC+09:00) Seoul",
  "Russia TZ 8 Standard Time": "(UTC+09:00) Yakutsk",
  "Cen. Australia Standard Time": "(UTC+09:30) Adelaide",
  "AUS Central Standard Time": "(UTC+09:30) Darwin",
  "E. Australia Standard Time": "(UTC+10:00) Brisbane",
  "AUS Eastern Standard Time": "(UTC+10:00) Canberra, Melbourne, Sydney",
  "West Pacific Standard Time": "(UTC+10:00) Guam, Port Moresby",
  "Tasmania Standard Time": "(UTC+10:00) Hobart",
  "Russia TZ 9 Standard Time": "(UTC+10:00) Vladivostok",
  "Central Pacific Standard Time": "(UTC+11:00) Magadan, Solomon Is., New Caledonia",
  "New Zealand Standard Time": "(UTC+12:00) Auckland, Wellington",
  "Fiji Standard Time": "(UTC+12:00) Fiji, Marshall Is.",
  "Kamchatka Standard Time": "(UTC+12:00) Petropavlovsk-Kamchatsky",
  "Tonga Standard Time": "(UTC+13:00) Nuku'alofa",
  "Bahia Standard Time": "(UTC-03:00) Salvador",
  "Syria Standard Time": "(UTC+02:00) Damascus",
  "North Asia East Standard Time": "(UTC+08:00) Irkutsk, Ulaan Bataar",
  "North Asia Standard Time": "(UTC+07:00) Krasnoyarsk",
  "Magadan Standard Time": "(UTC+12:00) Magadan",
  "N. Central Asia Standard Time": "(UTC+06:00) Almaty, Novosibirsk",
  "Ulaanbaatar Standard Time": "(UTC+08:00) Ulaanbaatar",
  "Vladivostok Standard Time": "(UTC+10:00) Vladivostok",
  "Yakutsk Standard Time": "(UTC+09:00) Yakutsk",
  "Ekaterinburg Standard Time": "(UTC+05:00) Ekaterinburg",
  "Cape Verde Standard Time": "(UTC-01:00) Cape Verde Is.",
  "Russian Standard Time": "(UTC+03:00) Moscow, St. Petersburg, Volgograd",
  "Bangladesh Standard Time": "(UTC+06:00) Dhaka"
}

Supported Languages

The key/value pairs for country codes that SigningHub recognizes .  These are used in various API calls and for setting the language preference when using tight integration iframe functionality.

  "en-US" : "English",
  "nl-NL" : "Nederlands",
  "es-ES" : "Español (ES)",
  "es-LA" : "Español (LA)",
  "fr-FR" : "Français",
  "de-DE" : "Deutsch",
  "ar-AE" : "العربية",
  "tr-TR" : "Türkçe",
  "lv-LV" : "Latviski",
  "nb-NO" : "Norsk",
  "el-GR" : "ελληνικά",
  "hi-IN" : "हिंदी",
  "id-ID" : "Bahasa Indonesia",
  "ja-JP" : "日本語",
  "pt-Pt" : "Português (PT)",
  "pt-BR" : "Português (Brasil)",
  "ro-RO" : "Română",
  "ru-RU" : "Pусский",
  "sr-CR" : "Srpski",
  "th-TH" : "ภาษาไทย",
  "vi-VN" : "Tiếng Việt",
  "zh-CN" : "简体中文",
  "it-IT" : "Italiano",
  "fi-FI" : "Suomo",
  "et-ET" : "Eesti",
  "pl-PL" : "Polski",
  "sv-SE" : "Svenska",
  "da-DK" : "Dansk",
  "cr-CR" : "Cрпски",