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

Cloud Signature Consortium (CSC) Signing

This section entails the web services for the Cloud Signature Consortium (CSC) Signing.

SigningHub APIs

SigningHub-supported APIs for performing document signing operations via the CSC Server.

Pre-Bulk CSC Signing

Business applications can use this API to get document hash (D2S) of multiple documents (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, stamp and initials fields. On the successful completion of bulk signing transaction, the API will return the statuses and transaction ids of the document packages.

This API not only prepare document hash of documents in packages 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.

You must call this API after the Bulk Signing Pre Validation API.

In case you need to make changes in any of the document before signing, the Save Package 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.

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
x-folder-id
string
Default: 0

Specify the folder ID, for retrieving the folder items, when a shared space folder is involved.

x-open-identity-verification
string
Default: 798h-879-k3jk5

The Identity Verification token obtained from Get Identity Verification Flow Status, if applicable. If the policy has not been set, then the value shall be null.

x-identity-verification
string
Default: 798h-879-k3jk5

The Identity Verification token obtained from Get Identity Verification Flow Status, if applicable. If the policy has not been set, then the value shall be null.

Request Body schema:
ids
Array of integers or null <int64>

An array of the document package ids that are selected for bulk signing.

hand_signature_initials_image
string or null

Base64 image required if initials are part of the workflow

hand_signature_initials_method
string (Enumerations.HandSignature)
Enum: "DRAW" "TEXT" "UPLOAD" "SIGNATURE_PAD" "NONE"
object (Models.StampInfoRequestModel)
hand_signature_image
string or null

A Base64 encoded image string is required in case of visible signature appearance.

hand_signature_method
string (Enumerations.HandSignature)
Enum: "DRAW" "TEXT" "UPLOAD" "SIGNATURE_PAD" "NONE"
signing_reason
string or null

Reason of signing provided by the recipient.

signing_location
string or null

Locale of the signer provided by the recipient

contact_information
string or null

Contact information of the signer provided by the recipient

appearance_design
string or null

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
required
string non-empty

Name of signing server using which the document is to be signed

credential_id
required
string non-empty

The unique identifier associated to the credential.

access_token
required
string non-empty

Bearer token return by authorization server

SAD
string or null

SAD return by RSSP (remote signing service provider) after credential authorization. It is required if SCAL value is 1 in credential info response.

transaction_id
string or null

re-initiated signing process transaction id

Responses

Request samples

Content type
{
  • "ids": [
    ],
  • "hand_signature_initials_image": "string",
  • "hand_signature_initials_method": "DRAW",
  • "stamp": {
    },
  • "hand_signature_image": "string",
  • "hand_signature_method": "DRAW",
  • "signing_reason": "string",
  • "signing_location": "string",
  • "contact_information": "string",
  • "appearance_design": "string",
  • "signing_server": "string",
  • "credential_id": "string",
  • "access_token": "string",
  • "SAD": "string",
  • "transaction_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "transaction_id": "string"
}

Post-Bulk CSC Signing

Business applications can use this service API to embed signatures in PDF/XML documents without displaying the documents to the end user.

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
x-folder-id
string
Default: 0

Specify the folder ID, for retrieving the folder items, when a shared space folder is involved.

Request Body schema:
transaction_id
required
string non-empty

The identification number of the bulk signing transaction

required
Array of objects (Models.CscRawSignature)

Signature details

Responses

Request samples

Content type
{
  • "transaction_id": "string",
  • "signatures": [
    ]
}

Response samples

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

Get Document Hash

Business applications can use this service API to get D2S (data to be signed) of PDF/XML document.

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 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
x-folder-id
string
Default: 0

Specify the folder ID, for retrieving the folder items, when a shared space folder is involved.

x-identity-verification
string

The Identity Verification token obtained from Get Identity Verification Flow Status, if applicable. If the policy has not been set, then the value shall be null.

Request Body schema:

Data that need to get document hash

field_name
required
string non-empty

Unique identifier of the signature field in the document.

hand_signature_image
string or null

A Base64 encoded image string is required in case of visible signature appearance. 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.)

hand_signature_method
string (Enumerations.HandSignature)
Enum: "DRAW" "TEXT" "UPLOAD" "SIGNATURE_PAD" "NONE"
signing_reason
string or null

Reason of signing provided by the recipient.

signing_location
string or null

Locale of the signer provided by the recipient.

contact_information
string or null

Contact information of the signer provided by the recipient.

appearance_design
string or null

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"

certificates
required
Array of strings

List of certificates Base64 obtained from credentials/info response

signing_server
required
string non-empty

Name of RSSP (remote signing service provider)

signing_algo
required
string non-empty

Signing algo that is obtained from credentials/info response as key/algo

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "hand_signature_image": "string",
  • "hand_signature_method": "DRAW",
  • "signing_reason": "string",
  • "signing_location": "string",
  • "contact_information": "string",
  • "appearance_design": "string",
  • "certificates": [
    ],
  • "signing_server": "string",
  • "signing_algo": "string"
}

Response samples

Content type
application/json
{
  • "hash": "string",
  • "state": "string",
  • "hashing_algo": "string"
}

Embed Signature

Business applications can use this service API to embed signature in PDF/XML document.

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 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
x-base64
required
string
Default: true

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

x-folder-id
string
Default: 0

Specify the folder ID, for retrieving the folder items, when a shared space folder is involved.

x-identity-verification
string

The Identity Verification token obtained from Get Identity Verification Flow Status, if applicable. If the policy has not been set, then the value shall be null.

Request Body schema:

Data that need to embed signature into the document

field_name
required
string non-empty

Unique identifier of the signature field in the document.

signing_server
required
string non-empty

Name of RSSP (remote signing service provider)

signature
required
string non-empty

Base64-encoded signed hash that get in the response of RSSP (remote signing service provider) request signatures/signHash

credential_id
required
string non-empty

The unique identifier associated to the credential.

skip_verification
boolean

No signature verification returns in response body when it is set as true. Default value for this parameter set to false.

state
required
string non-empty

Unique alphanumeric value per transaction

Responses

Request samples

Content type
{
  • "field_name": "string",
  • "signing_server": "string",
  • "signature": "string",
  • "credential_id": "string",
  • "skip_verification": true,
  • "state": "string"
}

Response samples

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

Get Account Token

Business applications can use this service API to get access token which is needed to resolve restricted access to authorization servers.

query Parameters
signing_server
string

RSSP (remote signing service provider) name. It must be URL encoded string to handle special characters.

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
{
  • "account_token": "string"
}

Sign Document via RSSP Directly

Business applications can use this service API to sign PDF/XML document when SCAL is 1 in credentials/info response.This API will generate D2S (data to be signed), get signature from RSSP (remote signing service provider) directly and then perform signature embedding.

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 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
x-base64
required
string
Default: true

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

x-folder-id
string
Default: 0

Specify the folder ID, for retrieving the folder items, when a shared space folder is involved.

x-identity-verification
string

The Identity Verification token obtained from Get Identity Verification Flow Status, if applicable. If the policy has not been set, then the value shall be null.

Request Body schema:

Data that need to sign document via RSSP (remote signing service provider)

access_token
string or null

Bearer token return by authorization server

field_name
required
string non-empty

Unique identifier of the signature field in the document.

signing_server
required
string non-empty

Name of RSSP (remote signing service provider)

credential_id
required
string non-empty

The unique identifier associated to the credential.

skip_verification
boolean

No signature verification returns in response body when it is set as true. Default value for this parameter set to false.

hand_signature_image
string or null

A Base64 encoded image string is required in case of visible signature appearance. 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.)

hand_signature_method
string (Enumerations.HandSignature)
Enum: "DRAW" "TEXT" "UPLOAD" "SIGNATURE_PAD" "NONE"
signing_reason
string or null

Reason of signing provided by the recipient.

signing_location
string or null

Locale of the signer provided by the recipient.

contact_information
string or null

Contact information of the signer provided by the recipient.

appearance_design
string or null

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"

certificates
required
Array of strings

List of certificates Base64 obtained from credentials/info response

sad
required
string non-empty

SAD return by RSSP (remote signing service provider) after credential authorization

signing_algo
required
string non-empty

signing algo that is obtained from credentials/info response as key/algo

Responses

Request samples

Content type
{
  • "access_token": "string",
  • "field_name": "string",
  • "signing_server": "string",
  • "credential_id": "string",
  • "skip_verification": true,
  • "hand_signature_image": "string",
  • "hand_signature_method": "DRAW",
  • "signing_reason": "string",
  • "signing_location": "string",
  • "contact_information": "string",
  • "appearance_design": "string",
  • "certificates": [
    ],
  • "sad": "string",
  • "signing_algo": "string"
}

Response samples

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

Unlock CSC Documents

Business applications can use this service API to unlock documents which is locked while csc signing.

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:
transaction_id
string or null

The identification number of the csc signing transaction

Responses

Request samples

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

Response samples

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

Get RSSP Information

Business applications can use this service API to get RSSP (remote signing service provider) information that need to perform CSC Signing.

query Parameters
signing_server
string

RSSP (remote signing service provider) name. It must be URL encoded string to handle special characters.

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
{
  • "host_url": "string",
  • "client_id": "string",
  • "authentication_required": true,
  • "authorization_required": true,
  • "authentication_via_proxy_required": true,
  • "time_out": 0,
  • "auth_type": "string"
}

CSC Server (Wrapper)

Wrapper APIs around CSC Server endpoints. SigningHub serves as a mediation layer between client applications and the CSC Server, handling request routing and response processing.

Revoke OAuth2 Access Token

Business applications can use this service API to revoke access token of RSSP (remote signing service provider).Use this API when Access Token need to be revoked by oauth2/revoke end-point.

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:

Data that need to revoke access token

access_token
required
string non-empty

The token that the signature application wants to get revoked.

oauth2_url
required
string non-empty

The base URI of the OAuth 2.0 authorization server endpoint supported by the remote service for service authorization and/or credential authorization.

signing_server
required
string non-empty

Name of RSSP (remote signing service provider)

Responses

Request samples

Content type
{
  • "access_token": "string",
  • "oauth2_url": "string",
  • "signing_server": "string"
}

Response samples

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

Get Access Token | SAD

Business applications can use this service API to get Access Token (Bearer) | SAD to make authorized calls and get signature respectively from RSSP (remote signing service provider).

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:

Data that need to get Access Token | SAD

code
string or null

Unique code return by RSSP (remote signing service provider) on service/credential authorization call

oauth2_url
required
string non-empty

The base URI of the OAuth 2.0 authorization server endpoint supported by the remote service for service authorization and/or credential authorization.

signing_server
required
string non-empty

Name of RSSP (remote signing service provider)

Responses

Request samples

Content type
{
  • "code": "string",
  • "oauth2_url": "string",
  • "signing_server": "string"
}

Response samples

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

Get Filtered Credential List

Business applications can use this service API to get credential list from RSSP (remote signing service provider) and filtered as per user RUT value if its enabled in API's web.config

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:

Data that need to get credentials list from RSSP (remote signing service provider)

access_token
required
string non-empty

Bearer token return by RSSP (remote signing service provider)

signing_server
required
string non-empty

Name of RSSP(remote signing service provider)

Responses

Request samples

Content type
{
  • "access_token": "string",
  • "signing_server": "string"
}

Response samples

Content type
application/json
{
  • "credentialIDs": [
    ]
}

Get RSSP Info

Business applications can use this service API to get RSSP (remote signing service provider) info.

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:

request data

signing_server
required
string non-empty

Name of RSSP (remote signing service provider)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "specs": "string",
  • "name": "string",
  • "logo": "string",
  • "region": "string",
  • "lang": "string",
  • "description": "string",
  • "authType": [
    ],
  • "oauth2": "string",
  • "methods": [
    ]
}

Get Credentials Info

Business applications can use this service API to get credential info from RSSP (remote signing service provider)

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:

Data that need to get credentials info from RSSP (remote signing service provider)

access_token
required
string non-empty

Bearer token return by RSSP (remote signing service provider)

signing_server
required
string non-empty

Name of RSSP(remote signing service provider)

credential_id
required
string non-empty

The unique identifier associated to the credential.

Responses

Request samples

Content type
{
  • "access_token": "string",
  • "signing_server": "string",
  • "credential_id": "string"
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "key": {
    },
  • "cert": {
    },
  • "authMode": "string",
  • "SCAL": "string",
  • "PIN": {
    },
  • "OTP": {
    },
  • "multisign": 0,
  • "lang": "string"
}

RSSP Credentials Authorization

Business applications can use this service API for credentials authorization from RSSP (remote signing service provider)

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:

Data that need for credentials authorization from RSSP (remote signing service provider)

document_name
string or null <= 500 characters

For single document sign, pass the document name and for bulk sign pass the comma separated package names. You may pass it when making implicit call, otherwise skip it

access_token
required
string non-empty

Bearer token return by RSSP (remote signing service provider)

signing_server
required
string non-empty

Name of RSSP(remote signing service provider)

credential_id
required
string non-empty

The unique identifier associated to the credential.

num_signatures
required
integer <int32>

The number of signatures to authorize from RSSP (remote signing service provider)

hash
Array of strings or null

One or more Base64-encoded hash values to be signed. It allows the server to bind the SAD to the hash(es), thus preventing an authorization to be used to sign a different content. If the SCAL parameter returned by credentials/info method, for the current credentialID is “2” the hash parameter SHALL be used and the number of hash values SHOULD correspond to the value in numSignatures. If the SCAL parameter is “1”, the hash parameter is OPTIONAL.

otp
string or null

The OTP provided by the user. It SHALL be used only when authMode from credentials/info method, is “explicit” and OTP/presence is not “false”.

pin
string or null

The PIN provided by the user. It SHALL be used only when authMode from credentials/info is “explicit” and PIN/presence is not “false”.

Responses

Request samples

Content type
{
  • "document_name": "string",
  • "access_token": "string",
  • "signing_server": "string",
  • "credential_id": "string",
  • "num_signatures": 0,
  • "hash": [
    ],
  • "otp": "string",
  • "pin": "string"
}

Response samples

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

Get Sign Hash from RSSP

Business applications can use this service API to sign hash/s from RSSP (remote signing service provider)

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:

Data that need to sign hash/s from RSSP (remote signing service provider)

access_token
required
string non-empty

Bearer token return by RSSP (remote signing service provider)

signing_server
required
string non-empty

Name of RSSP(remote signing service provider)

credential_id
required
string non-empty

The unique identifier associated to the credential.

hash
required
Array of strings

One or more Base64-encoded hash values to be signed. It allows the server to bind the SAD to the hash(es), thus preventing an authorization to be used to sign a different content. If the SCAL parameter returned by credentials/info method, for the current credentialID is “2” the hash parameter SHALL be used and the number of hash values SHOULD correspond to the value in numSignatures. If the SCAL parameter is “1”, the hash parameter is OPTIONAL.

sad
required
string non-empty

SAD return by RSSP (remote signing service provider) after credential authorization

signing_algo
required
string non-empty

signing algo that is obtained from credentials/info response as key/algo

hashing_algo
required
string non-empty

The OID of the algorithm to use for signing. It SHALL be one of the values allowed by the credential as returned in keyAlgo by the credentials/info method

Responses

Request samples

Content type
{
  • "access_token": "string",
  • "signing_server": "string",
  • "credential_id": "string",
  • "hash": [
    ],
  • "sad": "string",
  • "signing_algo": "string",
  • "hashing_algo": "string"
}

Response samples

Content type
application/json
{
  • "signatures": [
    ]
}

Send OTP via RSSP

Business applications can use this service API to send OTP via RSSP (remote signing service provider)

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:

Data that need to send OTP via RSSP (remote signing service provider)

access_token
required
string non-empty

Bearer token return by RSSP (remote signing service provider)

signing_server
required
string non-empty

Name of RSSP(remote signing service provider)

credential_id
required
string non-empty

The unique identifier associated to the credential.

Responses

Request samples

Content type
{
  • "access_token": "string",
  • "signing_server": "string",
  • "credential_id": "string"
}

Response samples

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

Revoke Access Token

Business applications can use this service API to revoke access token of RSSP (remote signing service provider).

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:

Data that need to revoke access token

access_token
required
string non-empty

The token that the signature application wants to get revoked.

signing_server
required
string non-empty

Name of RSSP (remote signing service provider)

Responses

Request samples

Content type
{
  • "access_token": "string",
  • "signing_server": "string"
}

Response samples

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