Image

VIDT API: Manual

Image

Learn how the VIDT API, VIDT Private Cloud & VIDT Smart Contract will seamlessly anchor data from any publisher platform and cloud service to multiple blockchains

 

Cloud and Platform integrations

Publishers are organisations and creators of digital files. The creation of files can be done using any (cloud-)software that can connect to a HTTPS endpoint. The SHA-256 hash of each file is calculated by the publisher and meta attributes (file type, file size, file extension, optional reference) of these files are defined by the publisher on the publisher server.

Image

API key

The push REST API is available at https://validation.v-id.org/bridge/push/?. The API is intended to process up to 100 files in a single request. API behavior and required data sent, depends on the number of files. The endpoint accepts JSON input and POST requests with 3 required global variables and always outputs JSON.

apikey (string) "YourAPIKey"
integrityhash (string, 64) sha256 of the concatenated string "YourAPISecret".jsonencoded(payload)
payload  (array / JSON)  all data to be pushed, depends on the required action, accepted as an array or in JSON format



Payload

To validate one or more files the payload would consist of a maximum of 5 variables.

action (string) "validate" (required)
label (string, max 80) your reference for the entire batch of files (optional)
memo (string, max 1,000) your private note for the entire batch of files (optional)
callback (string, url, max 500) callback for asynchronous processing (required for more than 10 files)
files (array)  all files to be pushed, minimum 1 (required)


IMPORTANT NOTE

Validating files by calculating the SHA-256 hash client-side is always preferred for easiest GDPR compliancy. Second best is adding the file as base64 which will never be stored by V-ID, but is indeed sent. Specifically for web applications that generate files on-the-fly, the option was added to validate files by URL. Though quickly implemented, this method is less secure.

V-ID will never store files when using our API, not even temporarily.


File details

The files array is processed indifferent to array keys used. The array keys used will be returned in the output for your reference and convenience.

For validating files, the following variables are used.

reference (string, max 40) Your unique ID or reference of the file (required when pushing more than 1 file) "YourUniqueID1"
hash (string, max 64) sha256 hash of the file (optional, either url/hash/base64 required) "d4b334b ..."
url (string, max 500) Location of the file (optional, either url/hash/base64 required) "https://www.v-id.org/Sample.pdf"
base64 (byte) base64 encoded file data (optional, either url/hash/base64 required) "/9j/4RjxR ..."
data (string, max 10MB) When a raw data string is to be certified (optional, name / size / type / extension no longer required) "Sample.pdf"
name (string, max 250) The file name including its extension (optional, required without url) "Sample.pdf"
size (int, max 11) File size in bytes (optional, required without url) 14231
type (string, max 128) Mime type of the file (optional, required without url) "application/pdf"
extension (string, max 4) Extension of the file (optional, required without url) "pdf"
note (string) Public note, hyperlinks allowed (optional) "<a href='#'>sample</a>"



Output

Single file (synchronous / realtime)
On succesful processing, the JSON output includes a numeric 'resultID'. This is the preferred and quickest method, though other methods are available to support a wider interoperability. 

More than 1 file, not more than 10 files (synchronous / realtime)
On succesful processing, the JSON output includes an array named 'results'. The array contains a list of files using the same keys as were pushed.
Per file your 'reference' (string) and the V-ID reference number 'resultID' (int) are returned. If you included the same file more than once, 'duplicate' is returned for that file with value '1'.

More than 10 files (asynchronous, request / response)
The callback URL is used to notify your server of completion per file, posting both 'reference' (string) and 'resultID' (int). This method does not support the use of the base64 variable. Please note a total request limit of 256MB applies. If you included the same file more than once, 'duplicate' is returned for that file with value '1'.

If any file fails
For realtime requests (10 or less files) a 'status' (int) following the default HTTP status codes is returned. If so, no files will be processed. Refer to the 'message' (string) for more information. 
For asynchronous requests (when more than 10 files are sent), the callback response will not include a 'resultID' (int) but will include a 'status' (int) and 'message' (string). All files will be processed individually, but not realtime.

Callback URL
The callback request sent from a V-ID server expects a JSON encoded output including at least a valid HTTP status code. Requests will be repeated at least 10 times until a valid response (with status 200) is received.

Sample POST sent to the callback URL on success ...
{"status":200,"reference":"YourUniqueID1","resultID":"31034132853"}
and in case of an error ...
{"status":406,"reference":"YourUniqueID1","message":"File fingerprint is not readable","result":"UNREADABLE"}

Sample, valid, response of the callback URL would be ...
{"status":200,"message":"Callback processed"}

V-ID will contact you if the callback URL repeatedly returns an invalid response or is repeatedly unavailable.

Notes

  • Online availability of your file is never required when either the 'hash' or 'base64' of the file is sent.
  • Your file is never downloaded nor temporarily stored on our servers. The fingerprint is extracted in memory when no 'hash' or 'base64' is included in your request.
  • After successful extraction of the fingerprint it is up to you to delete the file from current online storage.
  • There is no need for the validated file to be available online after the fingerprint was extracted and a 'resultID' was returned. 
  • In case you included a file that has been validated before (duplicate fingerprint), the 'resultID' refers to the first file validated. A 'resultID' will not be returned if you are not the owner of the duplicate found.

Use PDFs with read-only permission!

When time-stamping PDF-files it is preferred to use read-only PDFs. In this way the unique hash remains the same and doesn't get changed accidentally by opening and saving the file. 

Code Samples

👉 Callback Sample

👉 Push Sample

 

Security and speed for any size

VIDT Datalink is the ultimate architecture to handle any volume of files, with any level of secure blockchain anchoring, all with sufficient speed. The ease of integration with the VIDT API combined with limitless compatibility with other business software and optional cloud storage results in an extremely low barrier for adoption.

Image
Image
Image
Image
Image
Image

Want to learn more?


Help us to achieve our mission: Risk free business.


contact us
discover >