Documentation Powered by Redocly

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.
  • Visit the Ascertia Community Portal to find answers to 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 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.

Main Tags
Most Popular Pages
➤ Welcome
➤ Prerequisites
➤ Access Tokens
➤ Quick Integration
➤ Updates
➤ SignalR
➤ APIs Developer Guide
➤ Appendix
➤ Authentication
➤ Account Management
➤ Add Package
➤ Upload Document
➤ Get Workflow Details
➤ Sign Document

SigningHub Admin

This section covers administration of enterprise accounts in SigningHub. For more details about SigningHub APIs, click here

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.

Accounts

APIs for managing customer accounts, account subscriptions, and account-level administrative operations.

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 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_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 or null

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 or null

Job title of the new SigningHub user.

company_name
string or null

Company name of the new SigningHub user.

mobile_number
string or null

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 or null

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

user_password
string or null

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 or null

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 or null

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
boolean

User consent terms of service and privacy policies for account registration.

user_national_id
string or null

National identity number of the user. This helps to identify users in the workflow

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,
  • "user_national_id": "string"
}

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

The total number of records found with the provided search criteria.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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
{ }

Service Plans

APIs for creating, updating, cloning, deleting, and retrieving service plans and subscription offerings.

Get Service Plans

Business applications can use this service API to get service plans. An admin, who has permissions to manage service plans in his role, can get service plans.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Service Plan

Business applications can use this service API to add service plan. An admin, who has permissions to manage service plans in his role, can add service plan.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

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

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
name
required
string [ 1 .. 100 ] characters

Name of the service plan

type
required
string (Models.PlanType)
Enum: "INDIVIDUAL" "ENTERPRISE"
start_date
string or null <date-time>

Date on which the service plan expiry has started

end_date
string or null <date-time>

Date on which the service plan expiry has ended

features
required
Array of strings (Models.PLAN_FEATURES)
Items Enum: "ALLOW_FORM_FIELDS" "ALLOW_REVIEWER" "ALLOW_ATTACHMENTS" "ALLOW_INITIALS_FIELDS" "ALLOW_INPERSON_FIELDS" "ALLOW_INTEGRATION" "ALLOW_BULK_SIGNING" "SERVICE_PLAN_FEATURE_CLOUD_DRIVES" "ALLOW_EDITOR" "ALLOW_SEND_A_COPY" "ALLOW_ELECTRONIC_SEAL" "ALLOW_DOCUMENTS_ARCHIVE" "ALLOW_SMART_FORM" "ALLOW_STAMPS"

List of features available in the service plan. Possible values are mentioned above. ALLOW_ELECTRONIC_SEAL and ALLOW_INTEGRATION can be added only to the "Enterprise" service plan.

public
boolean

True, if service plan is public

required
object (Models.ServicePlanConstraintRequest)

Service Plan - Constraints request

required
object (Models.ServicePlanLevelOfAssuranceRequest)

Service Plan - Level of assurance request

object (Models.ServicePlanCertifyOptionRequest)

Service Plan - Certify option request

pdf_a_compliancy
boolean

True, If PDF Compliant

object (Models.ServicePlanAutoDeleteDocumentRequest)

Service Plan - Auto delete document request

add_unique_identifier
boolean

True, If to add a unique identifier field in the document header.

object (Models.SignaturePadResponse)

Service Plan - Signature pad response

signature_appearances
required
Array of strings

Signature appearances, possible values are COMPANY_LOGO, HAND_SIGNATURE, DETAILED_SIGNATURE.

required
Array of objects (Models.ServicePlanSigningServerRequest)

Signing Servers

Array of objects or null (Models.ServicePlanElectronicSealServerRequest)

Electronic Seal Signing Servers that can be added to the "Enterprise" service plan.

required
object (Models.ServicePlanProfileRequest)

ServicePlan - Profile Request

require_password
boolean

Indicates whether a password is required during user registration

object (Models.ServicePlanAuthenticationProfileRequest)

ServicePlan Authentication Profile Request

object (Models.ServicePlanIdvProfileRequest)

ServicePlan - IDV Profile Request

required
object (Models.ServicePlanEvidenceReportRequest)

ServicePlan Evidence Report Request

object (Models.ServicePlanOneTimePasswordRequest)

ServicePlan - One Time Password Request

time_based_one_time_password
boolean

True if TOTP are enabled for the service plan.

object (Models.ServicePlanSmtpServerRequest)

Service Plan - SMTP Server Request

object (Models.ServicePlanSmsNotificationRequest)

Service Plan - Sms Notification Request

object (Models.ServicePlanAutoDeleteUserRequest)

Service Plan - Auto Delete User Request

object (Models.ServicePlanBillingRequest)

Service Plan - Billing Request

Responses

Request samples

Content type
{
  • "name": "string",
  • "type": "INDIVIDUAL",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "features": [
    ],
  • "public": true,
  • "constraints": {
    },
  • "level_of_assurance": {
    },
  • "certify_options": {
    },
  • "pdf_a_compliancy": true,
  • "auto_delete_document": {
    },
  • "add_unique_identifier": true,
  • "signature_pad": {
    },
  • "signature_appearances": [
    ],
  • "signing_servers": [
    ],
  • "electronic_seal_servers": [
    ],
  • "verification_profile": {
    },
  • "require_password": true,
  • "authentication_profile": {
    },
  • "identity_verification": {
    },
  • "evidence_report": {
    },
  • "one_time_password": {
    },
  • "time_based_one_time_password": true,
  • "smtp_server": {
    },
  • "sms_notification": {
    },
  • "auto_delete_user": {
    },
  • "billing": {
    }
}

Response samples

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

Get Service Plan by ID

Business applications can use this service API to get service plan. An admin, who has permissions to manage service plans in his role, can get service plan.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

The OAuth access token obtained as a result of successful authentication via the "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",
  • "start_date": "string",
  • "end_date": "string",
  • "features": [
    ],
  • "type": "string",
  • "created_on": "string",
  • "public": true,
  • "constraints": {
    },
  • "level_of_assurance": {
    },
  • "certify_options": {
    },
  • "pdf_a_compliancy": true,
  • "auto_delete_document": {
    },
  • "add_unique_identifier": true,
  • "signature_pad": {
    },
  • "signature_appearances": [
    ],
  • "signing_servers": [
    ],
  • "electronic_seal_servers": [
    ],
  • "verification_profile": {
    },
  • "require_password": true,
  • "deprecated": true,
  • "authentication_profile": {
    },
  • "identity_verification": {
    },
  • "evidence_report": {
    },
  • "one_time_password": {
    },
  • "time_based_one_time_password": true,
  • "smtp_server": {
    },
  • "sms_notification": {
    },
  • "auto_delete_user": {
    },
  • "billing": {
    }
}

Update Service Plan

Business applications can use this service API to update service plan. An admin, who has permissions to manage service plans in his role, can update service plan.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

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

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
name
required
string [ 1 .. 100 ] characters

Name of the service plan

start_date
string or null <date-time>

Date on which the service plan expiry has started

end_date
string or null <date-time>

Date on which the service plan expiry has ended

features
required
Array of strings (Models.PLAN_FEATURES)
Items Enum: "ALLOW_FORM_FIELDS" "ALLOW_REVIEWER" "ALLOW_ATTACHMENTS" "ALLOW_INITIALS_FIELDS" "ALLOW_INPERSON_FIELDS" "ALLOW_INTEGRATION" "ALLOW_BULK_SIGNING" "SERVICE_PLAN_FEATURE_CLOUD_DRIVES" "ALLOW_EDITOR" "ALLOW_SEND_A_COPY" "ALLOW_ELECTRONIC_SEAL" "ALLOW_DOCUMENTS_ARCHIVE" "ALLOW_SMART_FORM" "ALLOW_STAMPS"

List of features available in the service plan, possible values are mentioned above.ALLOW_ELECTRONIC_SEAL and ALLOW_INTEGRATION can be updated only to the "Enterprise" service plan.

public
boolean

True, if service plan is public

deprecated
boolean or null

Deprecated: Default value for this parameter set to false

required
object (Models.ServicePlanConstraintRequest)

Service Plan - Constraints request

required
object (Models.ServicePlanLevelOfAssuranceRequest)

Service Plan - Level of assurance request

object (Models.ServicePlanCertifyOptionRequest)

Service Plan - Certify option request

pdf_a_compliancy
boolean

True, If PDF Compliant

object (Models.ServicePlanAutoDeleteDocumentRequest)

Service Plan - Auto delete document request

add_unique_identifier
boolean

True, If to add a unique identifier field in the document header.

object (Models.SignaturePadResponse)

Service Plan - Signature pad response

signature_appearances
required
Array of strings

Signature appearances, possible values are COMPANY_LOGO, HAND_SIGNATURE, DETAILED_SIGNATURE.

required
Array of objects (Models.ServicePlanSigningServerRequest)

Signing Servers

Array of objects or null (Models.ServicePlanElectronicSealServerRequest)

Electronic Seal Signing Servers that can be updated to the "Enterprise" service plan.

required
object (Models.ServicePlanProfileRequest)

ServicePlan - Profile Request

require_password
boolean

Indicates whether a password is required during user registration

object (Models.ServicePlanAuthenticationProfileRequest)

ServicePlan Authentication Profile Request

object (Models.ServicePlanIdvProfileRequest)

ServicePlan - IDV Profile Request

required
object (Models.ServicePlanEvidenceReportRequest)

ServicePlan Evidence Report Request

object (Models.ServicePlanOneTimePasswordRequest)

ServicePlan - One Time Password Request

time_based_one_time_password
boolean

True if TOTP are enabled for the service plan.

object (Models.ServicePlanSmtpServerRequest)

Service Plan - SMTP Server Request

object (Models.ServicePlanSmsNotificationRequest)

Service Plan - Sms Notification Request

object (Models.ServicePlanAutoDeleteUserRequest)

Service Plan - Auto Delete User Request

object (Models.ServicePlanBillingRequest)

Service Plan - Billing Request

Responses

Request samples

Content type
{
  • "name": "string",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "features": [
    ],
  • "public": true,
  • "deprecated": true,
  • "constraints": {
    },
  • "level_of_assurance": {
    },
  • "certify_options": {
    },
  • "pdf_a_compliancy": true,
  • "auto_delete_document": {
    },
  • "add_unique_identifier": true,
  • "signature_pad": {
    },
  • "signature_appearances": [
    ],
  • "signing_servers": [
    ],
  • "electronic_seal_servers": [
    ],
  • "verification_profile": {
    },
  • "require_password": true,
  • "authentication_profile": {
    },
  • "identity_verification": {
    },
  • "evidence_report": {
    },
  • "one_time_password": {
    },
  • "time_based_one_time_password": true,
  • "smtp_server": {
    },
  • "sms_notification": {
    },
  • "auto_delete_user": {
    },
  • "billing": {
    }
}

Response samples

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

Delete Service Plan

Business applications can use this service API to delete the service plan. An admin, who has permissions to manage service plans in his role, can delete the service plan.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

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

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

Responses

Response samples

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

Clone Service Plan

Business applications can use this service API to clone service plan. An admin, who has permissions to manage service plans in his role, can clone service plan.

path Parameters
id
required
integer <int32>
header Parameters
Authorization
required
string
Default: Bearer {access_token}

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

Content-Type
required
string
Default: application/json
Accept
required
string
Default: application/json
Request Body schema:
name
required
string [ 1 .. 100 ] characters

Name of the service plan that is to be added.

public
boolean

True, if the service plan is marked as public.

deprecated
boolean or null

Deprecated: Default value for this parameter set to false

Responses

Request samples

Content type
{
  • "name": "string",
  • "public": true,
  • "deprecated": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "start_date": "string",
  • "end_date": "string",
  • "features": [
    ],
  • "type": "string",
  • "created_on": "string",
  • "public": true,
  • "constraints": {
    },
  • "level_of_assurance": {
    },
  • "certify_options": {
    },
  • "pdf_a_compliancy": true,
  • "auto_delete_document": {
    },
  • "add_unique_identifier": true,
  • "signature_pad": {
    },
  • "signature_appearances": [
    ],
  • "signing_servers": [
    ],
  • "electronic_seal_servers": [
    ],
  • "verification_profile": {
    },
  • "require_password": true,
  • "deprecated": true,
  • "authentication_profile": {
    },
  • "identity_verification": {
    },
  • "evidence_report": {
    },
  • "one_time_password": {
    },
  • "time_based_one_time_password": true,
  • "smtp_server": {
    },
  • "sms_notification": {
    },
  • "auto_delete_user": {
    },
  • "billing": {
    }
}

Get Basic Service Plans

Business applications can use this service API to get service plans. An admin, who has permissions to manage service plans in his role, can get service plans.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Admin Authentication

APIs for authenticating SigningHub administrators and obtaining administrative 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
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

Responses

Response samples

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