Documentation Powered by Redocly

SigningHub Admin 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 Token
➤ Updates
➤ APIs Developer Guide
➤ Appendix
➤ Authentication
➤ Service Plans
➤ Account Management
➤ Billing Management
➤ Access Control
➤ Operator Logs
➤ Advanced Reports

Billing

The Billing Module manages and stores billing information for users, providing a centralized view of all billing-related data and transactions.

Get Billings

Business applications can use this service API to get billings. An admin who has permission to manage the billing in his role can get billings.

path Parameters
pageNo
required
integer <int32>

The page number to be retrieved.

records
required
integer <int32>

The total number of records to be retrieved in a page.

query Parameters
agreement-id
string

The agreement ID for WorldPay and the customer ID for Stripe.

billing-type
string

The billing type will contain ONLINE_BILLING | OFFLINE_BILLING | NO_BILLING | NO_BILLING_TRIAL.

user-email
string <= 255 characters

The email address of the billable user.

enterprise-name
string <= 255 characters

The name of the billable user's enterprise.

failed-payments
boolean

True, if the online payment records that failed due to any technical reason will be displayed.

date-from
string <date-time>

The date from which the billing will be retrieved. The value is expected to follow the ISO 8601 format. Following the format YYYY-MM-DD hh:mm:ss +00. As the values are for date fields, the hh:mm:ss +00 can be ignored.

asc
boolean

True, if the parameter to order the result set is ascending.

autoreset
boolean

True, if the billing will be auto reset.

payment-mode
string <= 255 characters

The payment mode will contain MONTHLY | YEARLY.

payment-type
string <= 255 characters

The payment type will contain PAY_REGULARLY | PAY_AS_YOU_GO.

service-plan-id
integer <int64>

The ID of the service plan.

service-plan-name
string

The name of the service plan.

sort-by
string

A parameter to specify the sorting criteria for the result set. The parameter values include: created_on | performed_by | user_name | enterprise_name | service_plan_name | payment_type | user_amount | expiry_date.

date-to
string <date-time>

Date until which the billing is to be retrieved. The value is expected to follow the ISO 8601 format. Following the format YYYY-MM-DD hh:mm:ss +00. As the values are for date fields, the hh:mm:ss +00 can be ignored.

transaction-id
string

The transaction ID for WorldPay and the charge ID for Stripe.

transaction-type
string

The transaction type will contain FIRST | RECURRENT.

user-name
string <= 255 characters

The name of the billable user.

header Parameters
x-search-text
string
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

x-search-text
string
Default: John

A parameter that represents the search text, if required. This is optional and without it, the entire list is returned. Furthermore, the recommended value for the search text parameter is in Base64 encoded format or plain text.

x-total-records
string
Default: 212

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Billing Details

Business applications can use this service API to get the billing details. An admin who has permission to manage the billing in his role can get the billing details.

path Parameters
id
required
integer <int64>

The billing ID.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Responses

Response samples

Content type
application/json
{
  • "billing_model": "string",
  • "ipaddress": "string",
  • "payment_number": 0,
  • "reference_number": "string",
  • "remarks": "string",
  • "transaction_id": "string",
  • "user_agent": "string",
  • "vat_amount": "string",
  • "vat_number": "string",
  • "provider": "string",
  • "type": "string"
}

Get Saved Searches

Business applications can use this service API to get the saved billing searches. An admin who has permission to manage the billing in his role can get the saved searches.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Billing Save Search

Business applications can use this service API to save a search filter. An admin who has permission to manage the billing in his role can save a search filter.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Request Body schema:
action_type
string or null

The action type. The possible values for “Action Type” are “WORLDPAY_RECURRENT_PAYMENT_FAILURE”, “WORLDPAY_AGREEMENT_TERMINATED” and “ALL_TRANSACTION”

agreement_id
string or null

The agreement ID of the save search criteria.

billing_type
string or null

The billing type of the account. The possible values for “Billing type” are “ONLINE_BILLING”, “OFFLINE_BILLING”, “NO_BILLING”, and “NO_BILLING_TRIAL”.

date_from
string or null

The date from which to search onwards.

date_to
string or null

The date up till which to search.

user_email
string or null

The email address for the save search criteria.

enterprise_name
string or null

The name of the enterprise for the save search criteria.

payment_mode
string or null

The payment mode. The possible values for “Payment Mode” are “MONTHLY”, and “YEARLY”.

payment_type
string or null

The payment type. The possible values for the “Payment Type” are “PAY_REGULARLY”, and “PAY_AS_YOU_GO”.

search_name
string or null

The name of the save search.

service_plan_id
integer or null <int64>

The service plan ID.

service_plan_name
string or null

The name of the service plan.

transaction_id
string or null

The transaction ID of the save search criteria.

user_name
string or null

The name of the user.

Responses

Request samples

Content type
{
  • "action_type": "string",
  • "agreement_id": "string",
  • "billing_type": "string",
  • "date_from": "string",
  • "date_to": "string",
  • "user_email": "string",
  • "enterprise_name": "string",
  • "payment_mode": "string",
  • "payment_type": "string",
  • "search_name": "string",
  • "service_plan_id": 0,
  • "service_plan_name": "string",
  • "transaction_id": "string",
  • "user_name": "string"
}

Response samples

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

Update Save Search

Business applications can use this service API to save a search filter. An admin who has permission to manage the billing in his role can update a search filter.

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

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Request Body schema:
action_type
string or null

The action type. The possible values for “Action Type” are “WORLDPAY_RECURRENT_PAYMENT_FAILURE”, “WORLDPAY_AGREEMENT_TERMINATED” and “ALL_TRANSACTION”

agreement_id
string or null

The agreement ID of the save search criteria.

billing_type
string or null

The billing type of the account. The possible values for “Billing type” are “ONLINE_BILLING”, “OFFLINE_BILLING”, “NO_BILLING”, and “NO_BILLING_TRIAL”.

date_from
string or null

The date from which to search onwards.

date_to
string or null

The date up till which to search.

user_email
string or null

The email address for the save search criteria.

enterprise_name
string or null

The name of the enterprise for the save search criteria.

payment_mode
string or null

The payment mode. The possible values for “Payment Mode” are “MONTHLY”, and “YEARLY”.

payment_type
string or null

The payment type. The possible values for the “Payment Type” are “PAY_REGULARLY”, and “PAY_AS_YOU_GO”.

search_name
string or null

The name of the save search.

service_plan_id
integer or null <int64>

The service plan ID.

service_plan_name
string or null

The name of the service plan.

transaction_id
string or null

The transaction ID of the save search criteria.

user_name
string or null

The name of the user.

Responses

Request samples

Content type
{
  • "action_type": "string",
  • "agreement_id": "string",
  • "billing_type": "string",
  • "date_from": "string",
  • "date_to": "string",
  • "user_email": "string",
  • "enterprise_name": "string",
  • "payment_mode": "string",
  • "payment_type": "string",
  • "search_name": "string",
  • "service_plan_id": 0,
  • "service_plan_name": "string",
  • "transaction_id": "string",
  • "user_name": "string"
}

Response samples

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

Delete Saved Search

Business applications can use this service API to delete the billing search filter. An admin who has permission to manage the billing in his role can delete the billing search filter.

path Parameters
id
required
integer <int64>

The ID of the search filter.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Responses

Response samples

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

Get User Information

Business applications can use this service API to get user information. An admin who has permission to manage the billing in his role can get the user information.

query Parameters
emailAddress
string
header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Transaction Logs

Business applications can use this service API to get the transaction logs. An admin who has permission to manage the billing in his role can get the transaction logs.

path Parameters
pageNo
required
integer <int32>

The page number to be retrieved.

records
required
integer <int32>

The total number of records to be retrieved in a page.

query Parameters
email
string

The email for the search criteria.

user-name
string

The username for the search criteria.

enterprise-name
string

The name of the enterprise for the search criteria.

service-plan-id
integer <int32>

The service plan ID for the search criteria.

service-plan-type
integer <int32>

The type of service plan by which the account is to be searched. The possible values for “Service Plan Type” are “INDIVIDUAL”, “ENTERPRISE”, and “NONE”.

payment-type
string

The payment type for the search criteria. The possible values for the “Payment Type” are “PAY_REGULARLY”, and “PAY_AS_YOU_GO”.

billing-type
string

The billing type of the account. The possible values for “Billing type” are “1 = ONLINE_BILLING”, “2 = OFFLINE_BILLING”, “3 = NO_BILLING”, and “4 = NO_BILLING_TRIAL”.

reason
string

The billing reason for the search criteria.

performed-by
string

The “performed by” for the search criteria.

date_from
string

The “From” date for the search criteria.

date-to
string

The “To” date for the search criteria.

agreement-id
string

The agreement id for the search criteria.

transaction-id
string

The transaction id for the search criteria.

action-type
string

The action type. The possible values for “Action Type” are “WORLDPAY_RECURRENT_PAYMENT_FAILURE”, and “WORLDPAY_AGREEMENT_TERMINATED”.

payment-type-criteria
string

The payment type for the search criteria.

sort-column
string

The column sort for the search criteria.

asc
boolean

The asc flag for the search criteria. The default value of the asc flag is false.

header Parameters
x-search-text
string
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

x-total-records
string
Default: 212

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Transaction Log Details

Business applications can use this service API to get the transaction log details. An admin who has permission to manage the billing in his role can get the transaction log details.

path Parameters
id
required
integer <int64>

The ID of the transaction log.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "Key": "string",
  • "Value": "string",
  • "Visible": true,
  • "Order": 0,
  • "certificate_base64": "string",
  • "Type": "string",
  • "processed_state": "string"
}

Export Billing Data

Business applications can use this service API to export the billing data in an Excel file. An admin who has permission to manage the billing in his role can export the billing data.

path Parameters
pageNo
required
integer <int32>
records
required
integer <int32>
query Parameters
agreement-id
string

The agreement ID for WorldPay and the customer ID for Stripe.

billing-type
string

The billing type will contain ONLINE_BILLING | OFFLINE_BILLING | NO_BILLING | NO_BILLING_TRIAL.

user-email
string <= 255 characters

The email address of the billable user.

enterprise-name
string <= 255 characters

The name of the billable user's enterprise.

failed-payments
boolean

True, if the online payment records that failed due to any technical reason will be displayed.

date-from
string <date-time>

The date from which the billing will be retrieved. The value is expected to follow the ISO 8601 format. Following the format YYYY-MM-DD hh:mm:ss +00. As the values are for date fields, the hh:mm:ss +00 can be ignored.

asc
boolean

True, if the parameter to order the result set is ascending.

autoreset
boolean

True, if the billing will be auto reset.

payment-mode
string <= 255 characters

The payment mode will contain MONTHLY | YEARLY.

payment-type
string <= 255 characters

The payment type will contain PAY_REGULARLY | PAY_AS_YOU_GO.

service-plan-id
integer <int64>

The ID of the service plan.

service-plan-name
string

The name of the service plan.

sort-by
string

A parameter to specify the sorting criteria for the result set. The parameter values include: created_on | performed_by | user_name | enterprise_name | service_plan_name | payment_type | user_amount | expiry_date.

date-to
string <date-time>

Date until which the billing is to be retrieved. The value is expected to follow the ISO 8601 format. Following the format YYYY-MM-DD hh:mm:ss +00. As the values are for date fields, the hh:mm:ss +00 can be ignored.

transaction-id
string

The transaction ID for WorldPay and the charge ID for Stripe.

transaction-type
string

The transaction type will contain FIRST | RECURRENT.

user-name
string <= 255 characters

The name of the billable user.

header Parameters
x-search-text
string
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

Responses

Response samples

Content type
application/json
"string"

Add Manual Billing

Business applications can use this service API to add manual billing. An admin who has permission to manage the billing in his role can add manual billing.

header Parameters
Authorization
required
string
Default: Bearer {access_token}

The access token obtained as a result of first authenticating with a client certificate to receive a subject token, then exchange the subject token using the Token Exchange endpoint. The certificate must belong to a SigningHub Administrator authorized to perform this action.

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

Client IP address, typically set by reverse proxy or load balancer

Accept-Language
string

Preferred language (e.g., en-US, ar-SA)

x-enterprise-id
string
Default: 123

Provide an integer enterprise ID (for example, "1") to access that specified enterprise.

Request Body schema:
agreement_id
string or null
duration
required
string non-empty
account_owner_email
required
string [ 1 .. 255 ] characters
remarks
required
string non-empty
sp_amount
required
number <double>
service_plan_name
required
string non-empty
price
number or null <double>
transaction_id
required
string non-empty
user_currency
required
string non-empty

Responses

Request samples

Content type
{
  • "agreement_id": "string",
  • "duration": "string",
  • "account_owner_email": "string",
  • "remarks": "string",
  • "sp_amount": 0,
  • "service_plan_name": "string",
  • "price": 0,
  • "transaction_id": "string",
  • "user_currency": "string"
}

Response samples

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