Introduction

Integrate VirtualSignature eSignature and customer onboarding applications directly into your everyday workflow

With our RESTful API (Representational State Transfer / Application Programming Interface), you can quickly integrate and build VirtualSignature features into your website or internal document management applications to give you more control over your document and customer onboarding workflow.

Before you start you will be supplied with an application key to use to connect via the API. This is then used to authenticate and you confirm that you are happy to connect to your account via the API.

URL endpoints listed below reference https://portal.virtualsignature.com
https://www.sinerix.net is also supported until further notice for backward compatibility.

Requests and Responses

Authentication

Before you can start using your application you must authorize that they are happy to conect via your application. To do this you must use the requestauth function. This will return a link to login to your account and authorise or reject the request.

When a user is sending through their own application or the application of an Admin user on their company account, authorisation is set by default and therefore this step is not required

Once the authorisation request is accepted, you can then use the sessionlogin function to generate a session key which will be valid for one hour and allow use of the functionality.

Requests

Once your authentication has been granted you can then make a request. Data is securely passed to us via HTTPS.

Request Header

Once you have requested user authorisation as described in the authorisation section then the session_key and application_key values are to be sent in the request header.

Request Body

All other data is to be sent in a POST request using the JSON format.

Return Data

All return data is in JSON format.

Webhooks & HTTP Callbacks

Webhooks are available to provide a HTTP callback when certain events occur. For more information on webhooks please login to your VirtualSignature account where you can find more information on setting up webhooks in your account settings.

One–time callback URLs can also be set for a transaction if required.

Request Authorisation

Before using an application for the first time the user must authorise use of it.

When a user is sending through their own application or the application of an Admin user on their company account, authorisation is set by default and therefore this step is not required

• URLhttps://portal.virtualsignature.com/api/requestauth
• MethodPOST
• Header Params

  Name	Description	Example
  api_key	Your Api Key	MyApiKey
  application_key	Application Key for the required application	A1B2C3D4E5F6
  user_email	email address of user you are requesting access for	sample@sample.com

• Success Response:
  • status => success
  • auth_link => A link for user to authorise
• Error Response:
  • status => failure
  • reason => a reason why the user autherisation can not be made

Create User login

Once a user has accepted your authorisation request you must now generate a session key for each time they wish to use your application.
This session key will then be valid for 1 hour.

The session key and application key are then used in the header for all subsequent API calls.

• URLhttps://portal.virtualsignature.com/api/sessionlogin
• MethodPOST
• Header Params

  Name	Description	Example
  api_key	Your Api Key	MyApiKey
  application_key	Application Key for the required application	A1B2C3D4E5F6
  user_email	email address of user you are requesting access for	sample@sample.com

• Success Response:
  • status => success
  • session_key => session key
  • session_expire_time => session expire time (unix timestamp)
• Error Response:
  • status => failure
  • reason => a reason why a session could not be created

Check User Session

Once a session has been created you can check the user deatils and expiry timestamp

• URLhttps://portal.virtualsignature.com/api/checksession
• MethodPOST
• Header Params

  Name	Description	Example
  application_key	Application Key for the required application	A1B2C3D4E5F6
  session_key	Session key for current user	9Z8Y7W6X5T4I3M

• Success Response:
  • status => success
  • email => email address of session user account
  • session_expire_time => session expire time (unix timestamp)
• Error Response:
  • status => failure
  • reason => a reason why a the session could not be checked

Sending a document with signatures

Send up to 12* documents to parties for signature, SecureCode SMS can be included where required. (Document limit is defined by your licence)

Tags can be placed for the positioning signatures, initials and other form fields

For more detailed information on the usage of Smart–Tags please Click Here

If no tags are supplied for a party then a signature tag will be positioned beneath the last occurence of text/images on the final page of each supplied document.
If there is not enough space to fit signatures below the content then a new blank page will be inserted. The same applies for if a witness party is included and a witness block tag has not been included in the document.

If the document does not require a printed signature/witness block then the "no_signatures" option must be set to true in the files information.

A Date stamp can also be placed on the document, this is not tied to a party and will print the completion date of the transaction. The stamp required for a date is {{date}}.

• URLhttps://portal.virtualsignature.com/api/signature
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  subject	A subject for this transaction	Non Disclosure Agreement	string	Yes	N/A
  message	An optional message that will be sent to all recipients	Please sign the document	string	No	No message will be sent
  parties	An array for each party to be included, this contains the name, email address, phone number and country code A tag can be assigned to each party and for each tag that appears on the document a signature will be positioned here.	See Parties
  documents	An array for each document to be included	See Documents
  folders	An array of folder names to be used in transaction	array("Folder AA", "Folder BB", "Folder CC")	array	No	Folders will not be used for the transaction
  case_reference	A optional case reference, to be displayed to the recipient and on the audit log	Case9876543456	string	No	Case reference not set
  selfsign	If the sender is to be included as a signing party. When using selfsign via the API, the sender will sign on transaction send.	true	boolean	No	false
  wait	Whether to wait for a response or not	false	bool	No	true
  sequential	Send to parties in sequence (only applies for more than one party)	false	boolean	No	Sequential settings in user account
  selfsign_last	When both selfsign and sequential are enabled the sign time, set the sender as the last to sign. By default the sender will be the first to sign.	true	bool	No	false
  signoff	Assign transaction completion rights to sender	false	boolean	No	false
  redirect_url	Custom URL to redirect a party to once they have completed/cancelled a transaction. If an invalid URL is supplied this will be ignored.	https://www.google.com/	string	No	No URL set
  auto_redirect	If set true and valid "redirect_url" supplied, page will automatically redirect	true	boolean	No	false
  reminders	Set up to 4 reminders in days from send date (Minimum 1, Maximum 28). Any repeated days will be ignored. To disable reminders set value to false.	array(2,4,6,8)	array	No	Reminder settings set in account
  expiry_days	Set expire time in days from send date (Minimum 1, Maximum 365)	30	integer	No	Exipry settings set in user account
  expiry_time	Set expire time as UNIX Timestamp. Must be greater than 1 hour from send time and less than 365 days. Will override any expiry_days value set	1654870628	integer	No	Exipry settings set in user account
  witnessing_type	Method of witnessing (only applicable when witness included in transaction) Valid options are "inperson" or "distance"	inperson	string	No	inperson
  notification_emails	Set to false to disable all notification emails for transaction. This will overwrite any account settings configured.	true	boolean	No	true
  confirmation_email	Set to false if you do not wish to recieve a confirmation email for the transaction.	true	boolean	No	true
  sms_pin	Set SMS Secure 2FA PIN option for transaction. sms_otp option still needs to be set for each party requiring a PIN code. Can be set to "onetime", "multi" or "everytime"	multi	string	No	single
  display_email	Define the display email to be used for the transaction. Value supplied must be a valid email up to a maximum length of 100	return@email.com	string	No	Display email as defined in account settings
  cc_recipients	An array for each CC recipient to be included. A CC recipient is copied in and notified when a transaction is created and complete. A CC reipient can also be given live access to the transaction.	See CC Recipients
  on_behalf	Send the current transaction on behalf of another user given they have granted the right. Supply the email address of the user the transaction is to be sent as. If the user has not granted access or the email address supplied in invalid the transaction will not be sent.	otheruser@email.com	string	No	N/A
  recipient_pdf	Define if recipient is to recieve signed documents via email on completion. If not set account default setting will be used.	true	boolean	No	Account default setting
  callback_url	URL to send one time webhook notification to upon transaction complete/cancelled. If an invalid URL is supplied this will be ignored. For more information about how webhooks work please login to your account and view "webhooks" under settings	https://callback.url	string	No	N/A
  return_completed**	If all parties are completed upon transaction being sent, return completed file	true	boolean	No	false

  **"return_completed" is only applicable when all parties have completed upon sending. For more information please read further on party data.

• Success Response (When wait set to true):
  • status => success
  • transaction =>
  • id => transaction id
  • transaction_ref => transaction reference
  • title => Transaction title
  • time => Transaction send time
  • parties =>
  • array of parties included in transaction
  Success Response (When wait set to false):
  • status => success
  • transaction_ref => transaction reference
• Error Response:
  • status => failure
  • reason => a reason why the transaction could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/signature

  
  

  {

  "subject":"Non Disclosure Agreement",

  "message":"Please Sign the document",

  "parties":{

  {

  "fname":"Michael",

  "sname":"Johnson",

  "email":"mike.johnson@sample.com",

  "sms":"09876543210",

  "cc":"44"

  }

  },

  "documents":{

  {

  file:base64 encoded file,

  name:NDA,

  ext:pdf

  }

  },

  "selfsign":false,

  "wait":true

  }

Create a link to add fields to a transaction

Upload up to 12* documents and return a link (valid for 5 minutes) that will take you to the "Document Editor" screen to add fields if required then send the document or save as a template.

• URLhttps://portal.virtualsignature.com/api/editorlink
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  documents	An array for each file to be included, this contains the base64 encoded data of the file, the name of the file and the original extension of the file Permitted file types currently include pdf, doc and docx.	See Documents
  folders	An array of folder names to be used in transaction	array("Folder AA", "Folder BB", "Folder CC")	array	No	Folders will not be used for the transaction
  subject	A subject for this transaction	Non Disclosure Agreement	string	No	N/A
  message	An optional message that will be sent to all recipients	Please sign the document	string	No	N/A
  parties	An array for each party to be included, this can contain the name, email address, phone number and country code	See Parties (optional when using editor link)
  persist_time	Time in seconds for the link to be active for between 300 and 172800 (5 minutes to 48 hours)	500	integer	No	300

• Success Response:
  • status => success
  • URL => Link (active for 5 minutes)
  • valid_until => time link expires
  • editor_link_id => id used to retrieve transaction id once sent
  • transaction_ref => reserved transaction reference for if transaction is successfully sent
• Error Response:
  • status => failure
  • reason => a reason why the link could not be created
• Sample:
  POST https://portal.virtualsignature.com/api/editorlink

  
  

  {

  "documents":{

  {

  file:base64 encoded file,

  name:NDA,

  ext:pdf

  }

  }

  }

Retrieve transaction ID from editor link ID

Use a returned editor link id to retrieve a transaction id.

• URLhttps://portal.virtualsignature.com/api/editorlinktransaction
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  editor_link_id	A returned editor link id	1234	integer	Yes	N/A

• Success Response:
  • status => success
  • transaction_id => 1234
  • transaction_ref => ABCDEF123456
• Error Response:
  • status => failure
  • reason => a reason why the transaction id could not be returned
• Sample:
  POST https://portal.virtualsignature.com/api/editorlinktransaction

  
  

  {

  "editor_link_id":1234

  }

Get the status of a transaction status that has been sent with the wait flag set to false

Return current status, status could be success, processing or failure

• URLhttps://portal.virtualsignature.com/api/getprocessingstatus
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  transaction_ref	Transaction Ref of transaction	ABCDEF123456	string	Yes	N/A

• Success Response:

  Please see Success response for when wait set to true

• Error Response:
  • status => failure
  • reason => a reason why the transaction could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/getprocessingstatus

  
  

  {

  "transaction_ref":"ABCDEF123456"

  }

Sending a SecureMail transaction

Send up to 12* documents to a single party for receipt only
(Document limit is defined by your licence)

• URLhttps://portal.virtualsignature.com/api/securemail
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  subject	A subject for this transaction	Non Disclosure Agreement	string	Yes	N/A
  message	An optional message that will be sent to all recipients	Please sign the document	string	No	No message will be sent
  parties	An array for each party to be included, this contains the name and email address Only one party can be included when using SecureMail	See Parties
  documents	An array for each document to be included	See Documents
  case_reference	A optional case reference, to be displayed to the recipient and on the audit log	Case9876543456	string	No	Case reference not set
  redirect_url	Custom URL to redirect a party to once they have completed/cancelled a transaction. If an invalid URL is supplied this will be ignored.	https://www.google.com/	string	No	No URL set
  reminders	Set up to 4 reminders in days from send date (Minimum 1, Maximum 28). Any repeated days will be ignored. To disable reminders set value to false.	array(2,4,6,8)	array	No	Reminder settings set in account
  expiry_days	Set expire time in days from send date (Minimum 1, Maximum 365)	30	integer	No	Exipry settings set in user account
  expiry_time	Set expire time as UNIX Timestamp. Must be greater than 1 hour from send time and less than 365 days. Will override any expiry_days value set	1654870628	integer	No	Exipry settings set in user account
  on_behalf	Send the current transaction on behalf of another user given they have granted the right. Supply the email address of the user the transaction is to be sent as. If the user has not granted access or the email address supplied in invalid the transaction will not be sent.	otheruser@email.com	string	No	N/A
  display_email	Define the display email to be used for the transaction. Value supplied must be a valid email up to a maximum length of 100	return@email.com	string	No	Display email as defined in account settings
  callback_url	URL to send one time webhook notification to upon transaction complete/cancelled. If an invalid URL is supplied this will be ignored. For more information about how webhooks work please login to your account and view "webhooks" under settings	https://callback.url	string	No	N/A

• Success Response (When wait set to true):
  • status => success
  • transaction =>
  • id => transaction id
  • transaction_ref => transaction reference
  • title => Transaction title
  • time => Transaction send time
  • parties =>
  • array of parties included in transaction
  Success Response:
  • status => success
  • transaction_ref => transaction reference
• Error Response:
  • status => failure
  • reason => a reason why the transaction could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/securemail

  
  

  {

  "subject":"Non Disclosure Agreement",

  "message":"Please Sign the document",

  "parties":{

  {

  "fname":"Michael",

  "sname":"Johnson",

  "email":"mike.johnson@sample.com",

  "sms":"09876543210",

  "cc":"44"

  }

  },

  "documents":{

  {

  file:base64 encoded file,

  name:NDA,

  ext:pdf

  }

  },

  }

Parties

Please see below a detailed description of the parties array

An array is to be used for each party to be included

A advisor party can be assigned, giving them rights to review the transaction before it being sent to signing parties. To indicate that a signing party is to be assigned by the advisor the "advisor_assign" flag can be used. A witness party can also be assigned with the witnessing type and used alongside the witnessing_type flag. A witnessing party can be assigned by a signing party using the "party_assign" flag. Advisors are limited to one per transaction. A transaction cannot be sent with only advisor and witness parties.

Items marked with a † are not applicable when sending SecureMail

Items marked with a ‡ are not applicable when sending with a party alias.

• Key	Description	Example	Type	Required	Default
  fname	Party first name	Michael	string	Yes**	N/A
  sname	Party surname	Smith	string	Yes**	N/A
  email	Party email address	mike.smith@email.com	string	Yes**	N/A
  sms †‡	Phone number to send SMS OTP/Notifications to	09876543210	string	No	N/A
  cc †‡	Country code for sms phone number (if different to UK +44)	44	string	No	44
  sms_notify †‡	Enable SMS notifications for party (Valid SMS number required)	true	boolean	No	false
  sms_otp †‡	Enable SMS PIN for party Valid SMS number required, if valid number is supplied then true by default PIN type will be one time unless set otherwise for transaction	true	boolean	No	true
  sms_notify_content †‡	Set the custom content for notifications SMS messages to party. # character is used as placeholder to indicate position of link in message, if no link is required do not add # character in message. Character limit for custom message is 140 characters and anything long will be cut off.	Please click on the link # Kind Regards, Sender	string	No	Default message content used
  message †‡	Private message for this party only	Hi Joe, please review the following	string	No	No Message Sent
  client_reference‡	A optional client reference, to be displayed on the audit log	Client9876543456	string	No	Client reference not set for party
  attachments*†‡	Array of attachments details to be requested from party (maximum of 2) A name is required If an attachment is defined as strict then the party cannot proceed without supplying it. Strict is set as false by default.	array(    array(     "name"=>"Bank Statement",     "strict"=>true    ),    array("name"=>"Utility Bill") )	array	No	N/A
  access_reference‡	Access information supplied by sender to be entered by party during transaction access. The party is required to enter the supplied reference correctly to access the transaction. The reference is limited to 6-15 characters (case insensitive). Up to 4 access references can be supplied per party. If a date value is required please provide in the following format: dd-mm-yyyy.	array( array( "title"=>"Passcode", "reference"=>"abc123" ) )	array	No	N/A
  seal_reference †‡	A reference to be added to seach seal input assigned to the party. Max Length 10 characters. Ignored if seal for party is not included.	ABC1234	string	No	N/A
  advisor †‡	Set party as a third party advisor (maximum one advisor per transaction)	true	boolean	No	false
  witness †‡	Set party as a witness (maximum two witnesses per transaction)	true	boolean	No	false
  assignment †‡	Assign a witness to a party at given index (Only applicable for witness parties). Each witness must be assigned to a unique party.	1	integer	No	false
  review †	When a transaction is sent sequentially and signoff is enabled, a review point can be set. The review point will come after the first party set in the sequence. If no review point is set then signoff will occur after the final party.	true	boolean	No	false
  advisor_assign †‡	Only applicable to signing parties when an advisor is included in the transaction. Allows an advisor to edit party details upon review.	true	boolean	No	false
  party_assign †‡	Only applicable to witnessing parties. Allows signing party to set by a witness details on review.	true	boolean	No	false
  signature †‡	To set the party as signed and completed for the transaction a signature can be supplied. This can be an auto signature, generated from the party name or a png or jpg image.	"auto" or array( "file"=>base64 image data, "ext"=>"png" )	string/array	No	N/A
  document_privacy †‡	Documents can be hidden from certain parties as required. If a document is hidden from a party then they will not be able to view it or receive a completed copy. All parties must view at least one document in the transaction and if a tag is set for a party they must have visibility of that document. To hide documents from parties supply an array of the document indexes to be hidden for that party.	array(0,3,5)	array	No	N/A
  alias*†	Include party aliases as alternatives to the primary party. For each alias an array is required detailing email, fname and sname.	array( array("email"=>"aliasone@email.com", "fname"=>"Alias", "sname"=>"One"), array("email"=>"aliastwo@email.com", "fname"=>"Alias", "sname"=>"Two") )	array	No	N/A
  idvalidate*†‡	Request ID Validate Process (Set to either aes or qes depending on what is required)	aes	string	No	N/A
  smartcheck_sof*†‡	Request Source Of Funds Check (Set to either sof1 or sof2 depending on which profile is required)	sof1	string	No	N/A
  smartcheck_kyc*†‡	Request Know Your Client (KYC) Check (Set to either kyc1 or kyc2 depending on which profile is required)	kyc1	string	No	N/A
  smartcheck_dir*†‡	Request Director Check	dir1	string	No	N/A
  smartcheck_profile*†‡	Request SmartCheck Preset Profile (Options listed below)	aes1	string	No	N/A
  smartcheck_location*†‡	Set SmartCheck Request location option (can be either "uk" or "international"). If the profile selected does not support an "international" request the request will default to "uk"	international	string	No	uk
  smartpay*†‡	SmartPay Payment Request consisting of the bank account id where money is to be sent (retrieved from user account), the amount being requested and a payment reference	array(  "id"=>"BA123456",  "amount"=>"50",  "reference"=>"Payment Request" )	array	No	N/A

  *Not applicable when making an editorlink request
  **Not required when "advisor_assign" or "party_assign" are enabled.

  Alternatively if a party instance has been created as detailed below, then the party instance can be used. The party instance must have been signed using the embeded signing block before sending.

  Name	Description	Example	Type	Required	Default
  party_instance_id	ID of party instance created using "createparty" method	12345	integer	No	N/A

  Smartcheck Preset Profile Options

  Label	Preset Profile	ID Validate Profile	KYC	International
  Advanced 3D Liveness + ID Document Check	aes	aes	-	No
  Advanced 3D Liveness + ID Document Check & KYC Report	aes1	aes	kyc1	No
  Advanced 3D Liveness + ID Document Check & Enhanced KYC Report	aes2	aes	kyc2	No
  Advanced 3D Liveness + ID Document Check & Enhanced KYC/AML Report	aes3	aes	kyc3	Yes
  Qualified 3D Liveness + NFC Signature Certificate	qes	qes	-	No
  Qualified 3D Liveness + NFC Signature Certificate & KYC Report	qes1	qes	kyc1	No
  Qualified 3D Liveness + NFC Signature Certificate & Enhanced KYC Report	qes2	qes	kyc2	No
  Qualified 3D Liveness + NFC Signature Certificate & Enhanced KYC/AML Report	qes3	qes	kyc3	Yes
  RTW/RTR Qualfied 3D Liveness and ePassport Check	rtr	rtr	-	No
  RTW/RTR Qualfied 3D Liveness and ePassport Check & KYC Report	rtr1	rtr	kyc1	No
  RTW/RTR Qualfied 3D Liveness and ePassport Check & Enhanced KYC Report	rtr2	rtr	kyc2	No
  RTW/RTR Qualfied 3D Liveness and ePassport Check Enhanced KYC/AML Report	rtr3	rtr	kyc3	No
  KYC - Credentials Report	kyc1	-	kyc1	No
  Enhanced KYC - Credentials & Fraud Report	kyc2	-	kyc2	No
  Full & AML including PEPs/Sanctions/Adverse Media	kyc3	-	kyc3	Yes

CC Recipients

Please see below a detailed description of the CC recipient array

An array is to be used for each CC recipient to be included

• Key	Description	Example	Type	Required	Default
  fname	Party First Name	Michael	string	Yes	N/A
  sname	Party Surname	Jones	string	Yes	N/A
  email	Party Email Address	michael.jones@email.com	string	Yes	N/A
  live	If party is granted live view access or not	true	boolean	No	false
  audit	If party is granted access to audit trail or not	true	boolean	No	true
  message	Optional private message to recipient (Max 500 characters)	Hi Joe, please monitor this transaction	string	No	No message set
  assigned	Transaction documents assigned to party, if all documents are to be assigned then set to true	array(1,2,4) This example would assign the first, second and fourth documents to the recipient	array/boolean	No	true

Create party instance prior to sending a transaction

Create an instance of a party before sending a transaction. This is only required when using the embeded signature block functionality. The first name, surname and email address of the party can be supplied to prefill the inputs in the embeded block.

• URLhttps://portal.virtualsignature.com/api/createparty
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  fname	Party First Name	Michael	string	No	N/A
  sname	Party Surname	Jones	string	No	N/A
  email	Party Email Address	michael.jones@sinerix.com	string	No	N/A
  button_label	Button label to be used in embeded signature block	Submit	string	No	APPLY ESIGNATURE
  preset_signature	Allow user to select preset signature option	true	boolean	No	true
  fields	Set if name and email fields are "open", "locked" or "hidden". Open fields can be viewed and edited by the signer, locked fields can be viewed but not edit and hidden fields are not displayed to the signer. If the fields are locked or hidden then a valid first name, surname and email address are required.	open	string	No	open
  header	Set header text to print	Please sign below	string	No	Confirm your first name, surname, email, then add your eSignature and click sign.

• Success Response:
  • status => success
  • party_instance_id => 12345
• Error Response:
  • status => failure
  • reason => a reason why the party instance could not be created
• Sample:
  POST https://portal.virtualsignature.com/api/createparty

  
  

  {

  "party_instance_id":12345

  }

Return Party Instance Summary

Return a party instance summary covering the past 7 days. For each day the number of party instances created and number of party instances signed will be returned.

• URLhttps://portal.virtualsignature.com/api/partysumary
• MethodPOST
• Success Response:
  • status => success
  • party_summary => party summary data
• Error Response:
  • status => failure
  • reason => a reason why the party summary could not be returned
• Sample:
  POST https://portal.virtualsignature.com/api/partysummary

Documents

Please see below a detailed description of the document array options.

An array is to be used for each document type to be included

Files

File types currently allowed are pdf, docx and doc.

Items marked with a † are not applicable when sending SecureMail

• Key	Description	Example	Type	Required	Default
  file	A base64 encoded file	base64 data	string	Yes	N/A
  name	An title for this document	Non disclosure agreement	string	Yes	N/A
  ext	The extension of the file being sent	pdf	string	Yes	N/A
  form_fields*†	By default all Adobe fields in a PDF document will be removed and ignored, to keep these as active fields set this value to "keep", to print the data in the fields and remove the active fields set this value to "print"	keep	string	No	All fields and data removed
  no_signatures*†	Do not add an auto signature tag if no tags are included in document	true	boolean	No	false
  do_not_return*†	Do not return a copy of the document to recipients on completion	false	boolean	No	false
  folder*	folder to assign document to as set in folders array. First folder in array is defined as 1 etc.	1	integer	No	N/A
  password*	Password to assign to the document. Passwords must be between 5 and 20 characters in length	ABCPass	string	No	N/A

  *Not applicable for SmartLink documents

Templates

• Key	Description	Example	Type	Required	Default
  template_id	ID of the template from your library	123456	integer	Yes	N/A
  no_signatures	Do not add an auto signature tag if no signatures in document	true	boolean	No	false

Forms

• Key	Description	Example	Type	Required	Default
  form_id	Form library ID	1234	integer	Yes	N/A
  form_replace	An array of pre defined fields to replace in the form. (Key = Field, Value = Replacement)	array( "address1" => "The Old Mill" "address2" => "Station Street" )	array	No	N/A
  form_field_default	An array for each input field to set the default value.	array( array( "name" => "sender_name" "value" => "John Smith" "readonly" => true ) )	See below
  section_remove	An array of pre defined sections to remove from the form. (A form is broken down into sections that work like building blocks, all sections are displayed by default)	array( "section3" "section6" )	array	No	N/A
  section_duplicate	An array of pre defined sections to duplicate from the form. A suffix is also required to allow distincting between replacement data and form field names. Replacement data in the duplicated section will appear in the following format {{DATAsuffix}} with form field names being altered in the same way.	array( array( "name" => "section2" "suffix" => "1" ) )	See below
  dynamic_table	An array of tables to dynamically generate within the form.	array( array( "name" => "dt-1" "headers" => array("name", "age") "data" => array( array("mike", "21"), array("dan", "22") ) ) )	See below
  dynamic_list	An array of lists to dynamically populate within the form.	array( array( "name" => "list1" "data" => array( "Car", "Train" ) ) )	See below
  do_not_return	Do not return a copy of the document to recipients on completion	false	boolean	No	false
  folder	folder to assign form to as set in folders array. First folder in array is defined as 1 etc. One form and one form only can be assigned to each folder.	1	integer	No	N/A
  password	Password to assign to the form. Passwords must be between 5 and 20 characters in length	ABCPass	string	No	N/A

Form Field Default

• Key	Description	Example	Type	Required	Default
  name	Name of form field to set value of	sender_name	string	Yes	N/A
  value	Value to set form field to	John Smith	string	Yes	N/A
  readonly	Whether to set form field to read-only or not	true	boolean	No	false

Section Duplicate

• Key	Description	Example	Type	Required	Default
  name	Name of form section to duplicate	section6	string	Yes	N/A
  suffix	Suffix string to be appended to form field data and field names in duplicated section Replacement data in the duplicated section will appear in the following format {{DATAsuffix}} with form field names being altered in the same way. A unique suffix is required for each form section duplication	1	string	Yes	N/A

Dynamic Tables

• Key	Description	Example	Type	Required	Default
  name	Name of table place holder to replace	dt-1	string	Yes	N/A
  headers	array of headers to use in the table	array("name", "age", "colour")	array	Yes	N/A
  data	array of arrays for each row in the table	array( array("mike", "21", "red"), array("dan", "32", "blue") )	array	Yes	N/A

All document types can be combined in a single transaction

Retrieve status and log for a transaction

Get status detailed log information for a given transaction

• URLhttps://portal.virtualsignature.com/api/gettransactionlog
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • transaction_log =>
  • transaction_id => ID of transaction
  • title => Transaction title
  • status => Current status
  • last_update => Last update date/time
  • documents => Array of any documents included
  • case_reference => Case reference (blank if not set)
  • parties => Array of each party including status and last update
  • action_log => Array of actions on transaction
• Error Response:
  • status => failure
  • reason => a reason why the transaction data could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/gettransactionlog

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Retrieve a list of pending transactions

Retrieve a list of your pending transactions with data including status and last update.
If applicable Failure status information is also returned for transactions sent with the wait flag set to "false". Failure information is only available for 3 days after the transaction was sent.
A limit of 5000 records can be retrieved per request.

• URLhttps://portal.virtualsignature.com/api/getpending
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  date_from	Start of optional date range in format dd/mm/yyyy or UNIX timestamp filtered by last update	03/08/2019	string	No	N/A
  date_to	End of optional date range in format dd/mm/yyyy or UNIX timestamp filtered by last update	20/08/2019	string	No	N/A
  defined_status	Filter results by a defined status that has previously been set	downloaded	string	No	N/A
  all_users	Retrieve data for all users in company (only available for admin level users)	true	bool	No	false

• Success Response:
  • status => success
  • transactions =>
  • pending =>array of pending mail data
• Error Response:
  • status => failure
  • reason => a reason why the pending transaction data could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getpending

  
  

  {

  "date_from":20/02/2019,

  "date_to":28/02/2019

  }

Retrieve a list of completed transactions

Retrieve a list of your completed transactions with data including status and last update
A limit of 5000 records can be retrieved per request.

• URLhttps://portal.virtualsignature.com/api/getcompleted
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  date_from	Start of optional date range in format dd/mm/yyyy or UNIX timestamp filtered by last update	03/08/2017	string	No	N/A
  date_to	End of optional date range in format dd/mm/yyyy or UNIX timestamp filtered by last update	20/08/2017	string	No	N/A
  defined_status	Filter results by a defined status that has previously been set	downloaded	string	No	N/A
  all_users	Retrieve data for all users in company (only available for admin level users)	true	bool	No	false

• Success Response:
  • status => success
  • transactions =>
  • completed =>array of completed mail data
• Error Response:
  • status => failure
  • reason => a reason why the completed transaction data could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getcompleted

  
  

  {

  "date_from":02/20/2017,

  "date_to":02/28/2017

  }

Retrieve completed transaction files

Get the completed PDFs for a given transaction (any attachments are also included)

• URLhttps://portal.virtualsignature.com/api/gettransactionfile
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A
  bundle	Return transaction documents bundled into one PDF file	true	boolean	No	false
  secure	Return secured transaction documents. Not applicable to any attachments or when transaction files are bundled.	true	boolean	No	false
  include_audit	Include audit file when returning bundled PDF (only applicable for bundling)	true	boolean	No	false

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • files => array of files
  • file => base64 encoded pdf file
  • name => file name
  • ext => file extension
  • type => file type (document or attachment)
  • context => for an attachment a context is returned indicating the source of the file
• Error Response:
  • status => failure
  • reason => a reason why the transaction file could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/gettransactionfile

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Retrieve transaction preview

Get a preview of transaction in current state (Only applicable to documents) Transaction preview is returned as a bundle of all documents.

• URLhttps://portal.virtualsignature.com/api/gettransactionpreview
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • files => array of files
  • file => base64 encoded pdf file
  • name => file name
  • ext => file extension
• Error Response:
  • status => failure
  • reason => a reason why the transaction preview could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/gettransactionpreview

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Retrieve completed audit log

Get the completed audit log PDF

• URLhttps://portal.virtualsignature.com/api/getauditfile
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • file => base64 encoded pdf file
• Error Response:
  • status => failure
  • reason => a reason why the audit file could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getauditfile

  
  

  {

  "transaction_ref":ABCEF123456

  }

Finalise a transaction

Finalise a given transaction that is currently pending sender review

• URLhttps://portal.virtualsignature.com/api/finalisetransaction
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the transaction could not be finalised
• Sample:
  POST https://portal.virtualsignature.com/api/finalisetransaction

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Cancel a transaction

Cancel a given transaction

• URLhttps://portal.virtualsignature.com/api/canceltransaction
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A
  notifications	If set to false the cancellation emails will not be sent to parties	false	bool	No	True

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the transaction could not be cancelled
• Sample:
  POST https://portal.virtualsignature.com/api/canceltransaction

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Resend Transaction Emails

Resend the transaction emails to parties for a given transaction, if party is not specified emails are resent to all parties

• URLhttps://portal.virtualsignature.com/api/resendtransactionemails
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A
  party_id	Party ID of party to recieve email	123456	integer	No	Email is resent to all parties

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the transaction emails could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/resendtransactionemails

  
  

  {

  "trans_id":123456

  }

Retrieve queries made on a transastion

Get query information for a given transaction

• URLhttps://portal.virtualsignature.com/api/getqueries
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • queries => array of queries made on transaction
  • id => unique id of query
  • email => email address of party making query
  • time => time query was made
  • message => query message
• Error Response:
  • status => failure
  • reason => a reason why the query data could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/gettransactionlog

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Purge files for a completed/cancelled transaction

Remove files from server for given transaction. Transaction must have been completed or cancelled. (All files are purged after 90 days by default)

• URLhttps://portal.virtualsignature.com/api/purgetransaction
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the transaction could not be purged
• Sample:
  POST https://portal.virtualsignature.com/api/purgetransaction

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Reassign transaction signoff

When transaction is awaiting completion sign–off from sender assign another person sign–off rights.
Transaction must have been set for sender completion rights and be completed by all parties.

• URLhttps://portal.virtualsignature.com/api/reassigntransactionsignoff
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A
  fname	First name of person sign– rights are to be assigned to.	John	string	Yes	N/A
  sname	Surname of person sign– rights are to be assigned to.	Smith	string	Yes	N/A
  email	Email address of person sign– rights are to be assigned to.	john.smith@example.com	string	Yes	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the assignment could not be made.
• Sample:
  POST https://portal.virtualsignature.com/api/reassigntransactionsignoff

  
  

  {

  "transaction_ref":"ABCDEF123456"

  "fname":"John"

  "sname":"Smith"

  "email":"john.smith@example.com"

  }

Set defined status for a transaction

Set a custom defined custom status for a transaction. This defined status is seperate to the overall status of the transaction. Once set the defined status will be retured when requested the /gettransactionlog, /getpending and /getcompleted endpoints alongside the timestamp the status was set.

• URLhttps://portal.virtualsignature.com/api/setdefinedstatus
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A
  defined_status	Status value to assign to the transaction. Must be an alphanumeric string maximum 20 characters in length	returned	string	No	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the status could not be set.
• Sample:
  POST https://portal.virtualsignature.com/api/setdefinedstatus

  
  

  {

  "transaction_ref":"ABCDEF123456"

  "defined_status":"returned"

  }

Generate a URL for transaction access

Generate a timed URL for a user (with rights to view the transaction) to directly access the case review screen for a given transaction, bypassing the login screen. The url will timeout 5 minutes after being generated.

• URLhttps://portal.virtualsignature.com/api/transactionaccess
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  transaction_ref	The transaction reference	ABCDEF123456	string	Yes	N/A

• Success Response:
  • status => success
  • url => access url
• Error Response:
  • status => failure
  • reason => a reason why a URL could not be genrated
• Sample:
  POST https://portal.virtualsignature.com/api/transactionaccess

  
  

  {

  "transaction_ref":"ABCDEF123456"

  }

Get a list of templates

List of transactions stored in your template library that can be sent for eSignature

• URLhttps://portal.virtualsignature.com/api/gettemplates
• MethodPOST
• Data Params N/A
• Success Response:
  • status => success
  • templates => array of items stored in library
  • template id =>
  • title =>template title
  • date_added =>date/time added to library
  • template_id => unique template id
  • documents => array of documents
  • names =>name of document
  • pages =>document page count
• Error Response:
  • status => failure
  • reason => a reason why the template list could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/gettemplates

Send a template from your library

Select a template from your library using a library ID

• URLhttps://portal.virtualsignature.com/api/signature
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  subject	A subject for this transaction	Non Disclosure Agreement	string	Yes	N/A
  message	An optional message that will be sent to all recipients	Please sign the document	string	No	No message will be sent
  documents	An array for each document to be included	See Documents
  parties	An array for each party to be included, this contains the name, email address, phone number and country code	See Parties

• Success Response:
  • status => success
  • transaction =>
  • id => transaction id
  • title => Transaction title
  • time => Transaction send time
  • parties =>
  • array of parties included in transaction
• Error Response:
  • status => failure
  • reason => a reason why the template could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/signature

  
  

  {

  "message":"Please Sign the document",

  "documents":{

  "template_id":123456

  },

  "parties":{

  {

  "fname":"Michael",

  "sname":"Johnson",

  "email":"mike.johnson@sample.com",

  "sms":"09876543210",

  "cc":"44"

  }

  }

  }

Remove a template from your library

Remove a template from your library that you on longer require.

• URLhttps://portal.virtualsignature.com/api/removetemplate
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  template_id	ID of the template to be removed from your library	123456	integer	Yes	N/A

• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the template could not be removed
• Sample:
  POST https://portal.virtualsignature.com/api/removetemplate

  
  

  {

  "trans_id":123456

  }

Retrieve a list of company users on your account

View a list of company users on your account along with the status, last account usage, team and user type. Pending invites will be included in the list with a user type of "InviteSent"

• URLhttps://portal.virtualsignature.com/api/getcompanyusers
• MethodPOST
• Data Params N/A
• Success Response:
  • status => success
  • users => array of account users
• Error Response:
  • status => failure
  • reason => a reason why the company user list could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getcompanyusers

Send an invite to a new company user

Invite a new company user onto your account (email domain must be allowed for your account)

• URLhttps://portal.virtualsignature.com/api/invitecompanyuser
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  email	The email address of the new company user being invited	new.user@sample.com	string	Yes	N/A
  user_type	The user type for the new invite (admin/teamadmin/teamleader/subuser)	admin	string	No	subuser
  team_id	A team_id for the new invite to be assigned to	123A456	string	No	N/A
  viewing_rights	Set user viewing rights (only applicable to a sub user in a team)	true	bool	No	false

• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the invite could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/invitecompanyuser

  
  

  {

  "email":"new.user@sample.com"

  }

Add a new company user

Add a new company user onto your account (email domain must be allowed for your account)

• URLhttps://portal.virtualsignature.com/api/addcompanyuser
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  email	The email address of the new company user being added	new.user@sample.com	string	Yes	N/A
  fname	The first name of the new company user being added	New	string	Yes	N/A
  sname	The surname of the new company user being added	User	string	Yes	N/A
  account_type	The account type for the new user (admin/teamadmin/teamleader/subuser)	admin	string	No	subuser
  team_id	A team_id for the new user to be assigned to	123A456	string	No	N/A
  viewing_rights	Set user viewing rights (only applicable to a sub user in a team)	true	bool	No	false

• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the invite could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/addcompanyuser

  
  

  {

  "email":"new.user@sample.com"

  }

Retrieve a list of company teams on your account

View a list of company teams on your account.

• URLhttps://portal.virtualsignature.com/api/getcompanyteams
• MethodPOST
• Data Params N/A
• Success Response:
  • status => success
  • users => array of account users
• Error Response:
  • status => failure
  • reason => a reason why the team list could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getcompanyteams

Update a user status on your account

Suspend/activate a user on your account.

• URLhttps://portal.virtualsignature.com/api/updateuserstatus
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  email	The email address of the user who is being updated	user@sample.com	string	Yes	N/A
  suspended	Whether the user is to be suspended or not	true	bool	Yes	N/A

• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the user status could not be updated
• Sample:
  POST https://portal.virtualsignature.com/api/updateuserstatus

Update a user team

Move a user to a new team given the team id

• URLhttps://portal.virtualsignature.com/api/updateuserteam
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  email	The email address of the user who is being updated	user@sample.com	string	Yes	N/A
  team_id	The team id to assign the user to (set to false to remove user from team)	12A34	string/false	Yes	N/A

• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the user team could not be updated
• Sample:
  POST https://portal.virtualsignature.com/api/updateuserteam

Update user type

Update user type (admin/teamadmin/teamleader/subuser) as required

• URLhttps://portal.virtualsignature.com/api/updateusertype
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  email	The email address of the user who is being updated	user@sample.com	string	Yes	N/A
  type	The user type (admin/teamadmin/teamleader/subuser) to set the user to	subuser	string	Yes	N/A

• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the user type could not be updated
• Sample:
  POST https://portal.virtualsignature.com/api/updateusertype

Update User viewing rights

Update user viewing rights (must be sub user assigned to a team)

• URLhttps://portal.virtualsignature.com/api/updateuserviewingrights
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  email	The email address of the user who is being updated	user@sample.com	string	Yes	N/A
  viewing_rights	Whether to enable or disable viewing rights for the user	true	bool	true	N/A

• Success Response:
  • status => success
  • users => array of account users
• Error Response:
  • status => failure
  • reason => a reason why the user viewing rights could not be updated
• Sample:
  POST https://portal.virtualsignature.com/api/updateuserviewingrights

Delete a company team

Delete a team from the company and assign all users to main company

• URLhttps://portal.virtualsignature.com/api/deleteteam
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  team_id	The team id to delete from the company	12A34	string	Yes	N/A

• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the user team could not be deleted
• Sample:
  POST https://portal.virtualsignature.com/api/deleteteam

On Behalf user list

Retrieve a list of users who have allowed you to send on their behalf

• URLhttps://portal.virtualsignature.com/api/onbehalflist
• MethodPOST
• Success Response:
  • status => success
  • users => array of users who have allowed you to send on their behalf
• Error Response:
  • status => failure
  • reason => a reason why the list of users could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/onbehalflist

Get Smartcheck Services

Retrieve a list of SmartCheck services available to the current user.

• URLhttps://portal.virtualsignature.com/api/getsmartcheckservices
• MethodPOST
• Success Response:
  • status => success
  • services => array of smartcheck services available to the current user
• Error Response:
  • status => failure
  • reason => a reason why the list of services could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getsmartcheckservices

Return account information for active user

Return information including licencing details and credits remaining availble for active user

• URLhttps://portal.virtualsignature.com/api/getaccountinfo
• MethodPOST
• Data Params N/A
• Success Response:
  • status => success
  • account => array of account information
• Error Response:
  • status => failure
  • reason => a reason why the account information could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getaccountinfo

Retrieve a list of preset messages available to user

Return the list of preset messages that have been set for the user

• URLhttps://portal.virtualsignature.com/api/getpresetmessages
• MethodPOST
• Data Params N/A
• Success Response:
  • status => success
  • messages => array of preset messages
• Error Response:
  • status => failure
  • reason => a reason why the messages could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getpresetmessages

Retrieve a list of availble HTML Forms

Retrieve a list of HTML forms that can be sent to parties to complete.

• URLhttps://portal.virtualsignature.com/api/getforms
• MethodPOST
• Data Params N/A
• Success Response:
  • status => success
  • forms => array of forms in library
• Error Response:
  • status => failure
  • reason => a reason why the form list could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getforms

Retrieve tag and field information for a form

Retrieve a list of tags and form fields that appear in the requested form.

• URLhttps://portal.virtualsignature.com/api/getforminfo
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  form_id	The HTML form ID	123456	integer	Yes	N/A

• Success Response:
  • status => success
  • title => Form title
  • tags => array of tags in form
  • fields => array of fields in form
• Error Response:
  • status => failure
  • reason => a reason why the form info could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getforminfo

Send an HTML form

Send an HTML form from your library for parties to complete and return.

• URLhttps://portal.virtualsignature.com/api/signature
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  subject	A subject for this transaction	Non Disclosure Agreement	string	Yes	N/A
  message	An optional message that will be sent to all recipients	Please sign the document	string	No	No message will be sent
  parties	An array for each party to be included, this contains the name, email address, phone number and country code	See Parties
  documents	An array for each document to be included	See Documents

• Success Response:
  • status => success
  • transaction =>
  • id => transaction id
  • title => Transaction title
  • time => Transaction send time
  • parties =>
  • array of parties included in transaction
• Error Response:
  • status => failure
  • reason => a reason why the form could not be sent
• Sample:
  POST https://portal.virtualsignature.com/api/signature

  
  

  {

  "subject":"Non Disclosure Agreement",

  "message":"Please Sign the document",

  "parties":[

  {

  "fname":"Michael",

  "sname":"Johnson",

  "email":"mike.johnson@sample.com",

  "sms":"09876543210",

  "cc":"44"

  }

  ],

  "documents":[{

  "form_id":"1234"

  "form_replace":{

  "address1":"The Old Mill",

  "address2":"Station Street",

  "town":"Myton",

  "country":"United Kingdom",

  }

  ]

  }

Retrieve HTML Form Data

Get data from HTML forms in JSON format, the forms must be part of a completed transaction

• URLhttps://portal.virtualsignature.com/api/getformdata
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • transaction =>
  • form_data => array for each form in transaction
  • data => json data
  • index => index of form in transaction
• Error Response:
  • status => failure
  • reason => a reason why data could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getformdata

  
  

  {

  "transaction_ref":ABCDEF123456

  }

Retrieve Smartcheck Report

Get the Smartcheck Reports when transaction pending review or completed

• URLhttps://portal.virtualsignature.com/api/getsmartcheckreport
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • files => array of files
  • file => base64 encoded pdf file
  • name => file name
  • ext => file extension
• Error Response:
  • status => failure
  • reason => a reason why the Smartcheck report could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getsmartcheckreport

  
  

  {

  "transaction_ref":ABCEF123456

  }

Retrieve Smartcheck Status

Get the Smartcheck status for all parties in the transaction

• URLhttps://portal.virtualsignature.com/api/getsmartcheckstatus
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  trans_id	The transaction ID	123456	integer	No*	N/A
  transaction_ref	The transaction reference	ABCDEF123456	string	No*	N/A

  *Either a transaction id or transaction reference is required
• Success Response:
  • status => success
  • parties => array of parties including their smartcheck status
• Possible status values are "not requested", "pending", "fail", "caution" or "pass"
• Possible values for each SmartCheck item are "N/A", "pending", "failure", "complete" or "void"
• Error Response:
  • status => failure
  • reason => a reason why the Smartcheck status could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getsmartcheckstatus

  
  

  {

  "transaction_ref":ABCEF123456

  }

Requesting a KYC/Director Check Report for an individual

Request a KYC report for an individual as required. The report can contain either or both a personal check and a director check

• URLhttps://portal.virtualsignature.com/api/kycrequest
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  smartcheck_kyc	Request a personal KYC Check (Set to either kyc1, kyc2 or kyc3 depending on which profile is required)	kyc1	string	No	N/A
  smartcheck_dir*†	Request Director Check	dir1	string	No	N/A
  fname	Party first name	Michael	string	Yes	N/A
  sname	Party surname	Smith	string	Yes	N/A
  mname	Party other names	Paul	string	No	N/A
  dob_day	Party Date of Birth Day (1-31)	11	integer	Yes (If requesting a personal check)	N/A
  dob_month	Party Date of Birth Month (1-12)	4	integer	Yes (If requesting a personal check)	N/A
  dob_year	Party Date of Birth Year (4 digit)	1985	integer	Yes (If requesting a personal check)	N/A
  address	Array of address arrays as detailed below.	array	array	At least one address required (If requesting a personal check)	N/A
  cno	Party Company Number	1685746476	string	Yes (If requesting a director check)	N/A

  Address Data

  Name	Description	Example	Type	Required	Default
  add1	Party Address Line 1	5 Station Road	string	Yes (If requesting a personal check)	N/A
  town	Party Address Town	Guildford	string	Yes (If requesting a personal check)	N/A
  postcode	Party Address Postcode	ABC123	string	Yes (If requesting a personal check)	N/A

• Success Response:
  • status => success
  • transaction =>
  • transaction_ref => transaction reference
  • smartcheck_report => base64 encoded file
• Error Response:
  • status => failure
  • reason => a reason why the report could not be returned
• Sample:
  POST https://portal.virtualsignature.com/api/kycrequest

  
  

  {

  "smartcheck_kyc":"kyc1"

  "fname":"Joe"

  "sname":"bloggs"

  "dob_day":11

  "dob_month":6

  "dob_year":1985

  "address":{[

  "add1":"5 station road"

  "town":"guildford"

  "postcode":"ABC123"

  ]}

  }

Requesting a Company Report

Request a Company Report given the company registration number

• URLhttps://portal.virtualsignature.com/api/companyreport
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  cno	Company Registration Number	1987654	string	Yes	N/A
  country	2 Letter ISO country code	GB	string	No	GB

• Success Response:
  • status => success
  • transaction =>
  • transaction_ref => transaction reference
  • smartcheck_report => base64 encoded file
• Error Response:
  • status => failure
  • reason => a reason why the report could not be returned
• Sample:
  POST https://portal.virtualsignature.com/api/companyreport

  
  

  {

  "cno":"1987654"

  }

Add smartlink data from an external source

Add smartlink data records from an external source

• URLhttps://portal.virtualsignature.com/api/addsmartlinkdata
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  sender_ref	A unique reference supplied by the sender to identify the record	ABC123	string	Yes	N/A
  smartlink_data	XML or JSON encoded data to be recorded (All data in the message section is stored)	XML or JSON data - see example below	string	Yes	N/A
  smartlink_user_id	User ID for data to be supplied to (default to active user)	12345678	integer	No	N/A
  documents	An array for each document to be included	See Documents		No	N/A

• Success Response:
  • status => success
  • smartlink_data_reference => Reference for smartlink data record
• Error Response:
  • status => failure
  • reason => a reason why the SmartLink data could not be added
• Sample:
  POST https://portal.virtualsignature.com/api/addsmartlinkdata

  
  

  {

  "sender_ref":"ABC123",

  "smartlink_data":"<messageblob><header></header><message><calltype>New Claim</calltype><line>383957</line><screen>HF OTHER</screen></message></messageblob>"

  }

Get supplied SmartLink data

Retrieve smartlink data records

• URLhttps://portal.virtualsignature.com/api/getsuppliedsmartlinkdata
• MethodPOST
• Data Params

  Name	Description	Example	Type	Required	Default
  date_from	Start of optional date range in format dd/mm/yyyy	03/08/2019	string	No	N/A
  date_to	End of optional date range in format dd/mm/yyyy	20/08/2019	string	No	N/A

• Success Response:
  • status => success
  • smartlink_data_records => Record for each smartlink data record
  • smartlink_data_reference => Reference for smartlink data record
  • sender_reference => Reference supplied by data sender
  • datetime => Date and time data record was created
  • data => array of data values
  • documents => array of any documents included
• Error Response:
  • status => failure
  • reason => a reason why the SmartLink data could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getsmartlinkdata

Retrieve a list of SmartPay bank accounts

Retrieve a list of SmartPay bank accounts available to the current user, the id can be used when making a smartpay request.

• URLhttps://portal.virtualsignature.com/api/getsmartpayaccounts
• MethodPOST
• Data ParamsN/A
• Success Response:
  • status => success
• Error Response:
  • status => failure
  • reason => a reason why the SmartPay account information could not be retrieved
• Sample:
  POST https://portal.virtualsignature.com/api/getsmartpayaccounts

Change Log

• Optional secured pdfs available on /gettransactionfile

August 2024

• Additional data returned for constituent parts in /getsmartcheckstatus
• Private message can now be set for CC recipient

April 2024

• New method to retrieve list of smartcheck services available to the user

March 2024

• Attachments requests can now be defined as strict if required

February 2024

• Company Report requests can now be made

January 2024

• Extended functionality on CC recipient allowing live view access and item assignment

November 2023

• Recipient PDF option can now be set per transaction

July 2023

• Witnesses can now be added when using /editorlink
• Additional SMS PIN options
• Link no longer added by default in SMS Notify content

June 2023

• User administration functionality
• SmartPay requests can be made
• Transaction preview PDF can now be retrieved

May 2023

• Party aliases are now available

April 2023

• Folders can now be set where required
• Account licence information can be retrieved for active user
• Document/SmartForm password protection

March 2023

• /kycrequest has now been added so KYC requested can be made directly by the sender
• A list of preset messages can now be retrieved that are available to the active user

February 2023

• Transactions can now be sent on behalf of another user given the access has been granted
• SelfSign tags can now be included in SecureMail requests
• A list of users the current user can send on behalf of can now be retrieved

January 2023

• Document privacy can now be set for parties as required
• SecureMail can now be sent through the API

December 2022

• Smartcheck report file can be retrieved for transactions that are awaiting sender review or are complete

November 2022

• Documents and Forms can now optionally be set to not return to recipient on completion
• Preset SmartCheck Profile can now be set
• Updates to editor link – Reserved transaction reference and set validity time
• ID Certificate file can be retrieved for transactions that are awaiting sender review or are complete
• Transaction finalisation can be triggered for transactions awaiting sender review

October 2022

• A custom defined status can now be set for a transaction

July 2022

• Documents can now be included alongside data Smartlink in requests

May 2022

• ID Validate can be set for party as required (aes/qes)

April 2022

• Expiry days can be set for each individual transaction

March 2022

• Authorisation not required when using own or admin user application

February 2022

• cc_recipients can be set when sending transactions
• All documents can be bundled into one PDF on gettransactionfile

January 2022

• SMS OTP and SMSNotify can be set as required
• Custom SMS content can be set when using SMS notify using sms_notify_content
• Custom display email can be set for a transaciton using display_email

December 2021

• When sending an Adobe form with fields, how the fields are treated can be set using adobe_fields

October 2021

• Sender sign time can be set when selfsign and sequential are both enabled using "selfsign_last" option

• keep_fields can be set for a document to retain Adobe fields as active fields in a document

July 2021

• Set recipient review index as detailed in "review" under party data
• Allow SmartForms to be added via /editorlink endpoint