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
    NameDescriptionExample
    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
    NameDescriptionExample
    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
    NameDescriptionExample
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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.

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

    NameDescriptionExampleTypeRequiredDefault
    party_instance_id ID of party instance created using "createparty" method 12345 integer No N/A

    Smartcheck Preset Profile Options

    LabelPreset ProfileID Validate ProfileKYCInternational
    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

  • KeyDescriptionExampleTypeRequiredDefault
    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
    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
    NameDescriptionExampleTypeRequiredDefault
    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

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

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

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

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

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

  • KeyDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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"
  • 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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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
    NameDescriptionExampleTypeRequiredDefault
    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 DocumentsNoN/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
    NameDescriptionExampleTypeRequiredDefault
    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

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