IntroductionLanguagesRequests query parametersRequests response structureRetrieving plan typeBest practices and security considerationsBefore you beginTerminologyGetting startedGroupsFilesFoldersTemplatesEmail templatesAppsErrors
Authorization
Accounts
Entities
User accounts
Introduction
SmartVault's REST API is a service for developers using the SmartVault storage system. The API provides web, mobile, and on-premises applications the ability to easily access SmartVault's document management capabilities.
Base url
https://rest.smartvault.com
Languages
The SmartVault API supports JSON, XML and the Google Protocol Buffer format, with XML being the default.
Add the following header to your requests if you want to get JSON responses: "Accept: application/json".Through the documentation, you'll find tables with API requests in different languages; all of this are done using the header above to get the response in JSON format.
Use application/x-protobuf if you want to use the Google Protocol Buffer format.
Requests query parameters
SmartVault API exposes some query parameters applicable to any request that helps returning extra parameters or to identify the entity structure.
The "eprop" query parameterTells the server to return extended property information in the results. It may be set to "0", "1", "true" or "false". Default is false.
Show eprop prop difference
The "vprop" query parameterTells the server to return extended version information in the results. It may be set to "0", "1", "true" or "false". Default is false.
Show vprop prop difference
The "children" query parameterSpecifies the depth of children to fetch back. 0 is just the element specified, and 1 is just the direct children. Can be any integer value "0" or greater. Default is 0.
Show children prop difference
Requests response structure
By default, any SmartVault API call will return the following object:
{"error": {"success": boolean},"message": { } //This message object will show only if the request was done correctly without any errors; more info below.}
For an API call where any errors occurred, the "success" property of the "error" object will be set to "false", the "message" object won't show at all in the response and an error object structure will be present in the response.
Retrieving plan type
If you know which kind of pricing plan you are using, know that "SmartVault for Business" is relative to non structured plans while "SmartVault for Accountants" will yield in a structured plan.
In case you don't know which pricing plan you are using, you can always check using the following API request.
https://rest.smartvault.com/nodes/pth?children=1&eprop=true
This call will return information about the account structure.
Show content
Search for the "accountExProperties" object in the result.
You need to specify both query parameters "children" and "eprop" for it to show up.If the key "FeatureAccountingPackage" in the "features" object is set to true, that means you are working with a Structured plan, otherwise, you are dealing with the non structured one.
More info about account types here
Best practices and security considerations
Use a TLS library that validates server identity.An improved implementation would ensure the identity of the SmartVault host. Perform this by retrieving the X509 certificate associated with smartvault.com and use it to validate the endpoint.
Access tokens should be carefully managed.During the OAuth autonomous flow, you will be granted an access token capable of impersonating the target User Id. This token will expire; however, be aware of malicious browser plug-ins that could be installed by an end user to sniff out this token by accessing the DOM. These tokens should be restricted in what they are allowed to perform and carefully protected.
Revoke access when no longer needed.You can control whether or not your client id is valid by logging into the SmartVault developer portal and changing settings. Further, you can control what activities this client id is allowed to perform. Restrict access to the bare necessity.
Properly manage the RSA private key used to perform the autonomous OAuth flow.Different keys should be generated for testing vs. production. Production keys should be properly managed and access should be restricted to the minimum staff members possible. With access to this key, others could impersonate your application and perform malicious activities.
Rotate your RSA private key at least once a year.Good key hygiene suggests these keys should be rotated at least once a year or anytime the key is suspected or confirmed of being shared improperly.