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.
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.
Once your authentication has been granted you can then make a request. Data is securely passed to us via HTTPS.
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.
All other data is to be sent in a POST request using the JSON format.
All return data is in JSON format.
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.
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
| 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 |
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.
| 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 |
Once a session has been created you can check the user deatils and expiry timestamp
| Name | Description | Example |
|---|---|---|
| application_key | Application Key for the required application | A1B2C3D4E5F6 |
| session_key | Session key for current user | 9Z8Y7W6X5T4I3M |
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}}.
| 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.
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.
| 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 |
Use a returned editor link id to retrieve a transaction id.
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| editor_link_id | A returned editor link id | 1234 | integer | Yes | N/A |
Return current status, status could be success, processing or failure
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| transaction_ref | Transaction Ref of transaction | ABCDEF123456 | string | Yes | N/A |
Please see Success response for when wait set to true
Send up to 12* documents to a single party for receipt only
(Document limit is defined by your licence)
| 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 |
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 |
| 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 |
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 |
| 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 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.
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| fname | Party First Name | Michael | string | No | N/A |
| sname | Party Surname | Jones | string | No | N/A |
| 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 |
Please see below a detailed description of the document array options.
An array is to be used for each document type to be included
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 | 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
| 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 |
| 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 |
| 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 |
| 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 |
| 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
Get status detailed log information for a given transaction
| 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 |
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.
| 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 |
Retrieve a list of your completed transactions with data including status and last update
A limit of 5000 records can be retrieved per request.
| 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 |
Get the completed PDFs for a given transaction (any attachments are also included)
| 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 |
| include_audit | Include audit file when returning bundled PDF (only applicable for bundling) | true | boolean | No | false |
Get a preview of transaction in current state (Only applicable to documents) Transaction preview is returned as a bundle of all documents.
| 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 |
Get the completed audit log PDF
| 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 |
Finalise a given transaction that is currently pending sender review
| 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 |
Cancel a given transaction
| 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 |
Resend the transaction emails to parties for a given transaction, if party is not specified emails are resent to all parties
| 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 |
Get query information for a given transaction
| 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 |
Remove files from server for given transaction. Transaction must have been completed or cancelled. (All files are purged after 90 days by default)
| 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 |
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.
| 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 address of person sign– rights are to be assigned to. | john.smith@example.com | string | Yes | N/A |
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.
| 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 |
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.
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| transaction_ref | The transaction reference | ABCDEF123456 | string | Yes | N/A |
List of transactions stored in your template library that can be sent for eSignature
Select a template from your library using a library ID
| 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 | |||
Remove a template from your library that you on longer require.
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| template_id | ID of the template to be removed from your library | 123456 | integer | Yes | N/A |
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"
Invite a new company user onto your account (email domain must be allowed for your account)
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| 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 |
Add a new company user onto your account (email domain must be allowed for your account)
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| 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 |
View a list of company teams on your account.
Suspend/activate a user on your account.
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| 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 |
Move a user to a new team given the team id
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| 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 |
Update user type (admin/teamadmin/teamleader/subuser) as required
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| 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 |
Update user viewing rights (must be sub user assigned to a team)
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| 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 |
Delete a team from the company and assign all users to main company
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| team_id | The team id to delete from the company | 12A34 | string | Yes | N/A |
Retrieve a list of users who have allowed you to send on their behalf
Retrieve a list of SmartCheck services available to the current user.
Return information including licencing details and credits remaining availble for active user
Return the list of preset messages that have been set for the user
Retrieve a list of HTML forms that can be sent to parties to complete.
Retrieve a list of tags and form fields that appear in the requested form.
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| form_id | The HTML form ID | 123456 | integer | Yes | N/A |
Send an HTML form from your library for parties to complete and return.
| 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 | |||
Get data from HTML forms in JSON format, the forms must be part of a completed transaction
| 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 |
Get the Smartcheck Reports when transaction pending review or completed
| 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 |
Get the Smartcheck status for all parties in the transaction
| 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 |
Request a KYC report for an individual as required. The report can contain either or both a personal check and a director check
| 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 |
| 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 |
Request a Company Report given the company registration number
| 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 |
Send a SmartLink form request to a recipient for them to fill in the requested details and have them returned.
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| smartlink_form_id | The ID of the SmartLink form as defined | 123456 | integer | Yes | N/A |
| reference | A reference defined by the sender, used when sending data back after form completion | R123/978 | string | Yes | N/A |
| email address of recipient | mail@test.com | string | No | No email will be sent | |
| sms | phone number of recipient to send SMS to | 09876543210 | string | No | No SMS will be sent |
| cc | country code for phone number | 44 | string | No | 44 |
| message_replace | array of content to be replaced in the SmartLink message | array( "introducer" => "A Co Ltd" ) |
array | No | N/A |
Retrieve data from a smartlink form that has been completed by the recipient
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| smartlink_id | The ID of the SmartLink request | 123456 | integer | Yes | N/A |
Retrieve completion status and data of all SmartLink forms that have been sent
| Name | Description | Example | Type | Required | Default |
|---|---|---|---|---|---|
| date_from | Start of optional date range in format dd/mm/yyyy filtered by last update |
03/08/2019 | string | No | N/A |
| date_to | End of optional date range in format dd/mm/yyyy filtered by last update |
20/08/2017 | string | No | N/A |
| complete_only | Return data for completed smartlink forms only | true | boolean | No | false |
Add smartlink data records from an external source
| 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 | |
Retrieve smartlink data records
| 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 |
Retrieve a list of SmartPay bank accounts available to the current user, the id can be used when making a smartpay request.