API Base URL: https://api-platform.vntana.com
For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.
Another feature offered on the VNTANA Platform is the ability to upload attachments to your Product’s in a variety of forms. Attachments can be files of types .png, .jpg, .gif, .mov, .mp4 and many more. They can also be uploaded to different entities relating to your Product. These entities are the Product itself, Configurators, Comments, Annotations, and Hotspots. This feature allows you to add reference videos or images to your products whether for internal use or customer reference. Do note there is a max size allowable for all attachments at 10 MB.
Note: For Hotspots, you cannot attach videos in the same manner, for these they have to be a linked video as Hotspots will be visible to any user with an embed link.
When creating and uploading Attachments via the API, there are two different processes depending on where you are uploading the Attachment. If you wish to upload it simply to a Product, you can directly do this using a single endpoint. If you want to add it to a Configurator or a Comment then you will have to first upload the attachment to the Client / Folder and then add to the Configurator or Entity. This guide will show the process of uploading an attachment to a Product and a Configurator.
Required Initial Steps
Before you can upload the Attachment via the API, you will need to Authenticate. Below is a quick summary of the steps involved, see our guide on Authentication to get a more detailed look at the process.
-
Log in using an Authentication Key or email / password.
-
Returns an x-auth-token in the Response Headers.
-
-
Retrieve a list of Organizations and store the needed Organization’s UUID.
-
Pass the x-auth-token from Step 1 in the Request Headers.
1{ ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token } -
This step can be skipped if the Organization UUID is already stored locally.
-
-
Generate a Refresh Token for the Organization.
-
Pass the x-auth-token from Step 1 in the Request Headers.
1234{‘x-auth-token’ : ‘Bearer ‘ + x_auth_token‘organizationUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
-
Retrieve a list of Clients / Folders and store the needed UUID.
-
Pass the x-auth-token in the Request Headers.
-
This step can be skipped if the Client / Folder UUID is already stored locally.
-
-
Generate a Refresh Token for the Client / Folder (Organization Admin / Owner users must skip this step).
-
Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Client UUID’s.
12345{‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
The Client / Folder UUID needs to be retrieved, if it is not stored locally or already retrieved via Authentication, you can search for the Client / Folder using the API. This endpoint will return a list of Client’s / Folder’s in the Organization and you can verify the correct one using the name or slug. Below is an example of this endpoint.
The Request structure is as follows:
The Response structure is as follows:
Now that you have a Client / Folder UUID you are ready to upload the Attachment.
Uploading Attachment to a Product
Uploading an attachment to a Product is the most straightforward of the Attachment methods. With valid authentication and the Client / Folder UUID in hand, you will just need to obtain the Product’s UUID that you wish to upload to if it isn’t stored locally, and then upload the attachment directly to it, as shown below.
To retrieve the Product UUID if it isn’t stored locally, you can do a search using a parameter of your choice including Tag UUID, Tag Name, Attribute, or simply the name of the Product. You can view our guide of Product Searches here, or to search for a Product using the expected name, use the below endpoint. Note: Products in Draft status will not be returned by Product searches, only those in either the Live Internal or Live Public state will be returned by the API.
The Request is structured as follows:
The Response is structured as follows:
The searches are fuzzy, meaning they return results based on relevance. Unless every Product name is quite unique, you’ll likely have to iterate over the results to match the name exactly.
With the necessary information, you can use the following endpoint to upload your Attachment.
Uploading Attachment to Configurator
Adding an Attachment to anything else is a little more involved. In order to add an Attachment to a Configurator, you must first upload the file to the Client / Folder the Entity exists in. Using the Client / Folder UUID obtained above, you can use the following endpoint to upload the file:
A successful response will return the following data:
The key value returned here is blobId which will be used in subsequent methods to add the Attachment to a Configurator. To add the attachment to a Configurator, you will need the Configurators UUID. You can view our Configurator guide to get a detailed look at searching for Configurators, or use the following sample:
The Request is structured as follows:
The Response is structured as follows:
You can use the name in the response to pinpoint the correct Configurator.
To then upload the attachment to the Configurator you can use the following endpoint.
This will return the attachment’s UUID upon successful upload.
Attachments can also be added to Comments, Annotations, and Hotspots. These will follow a similar process as adding to a Configurator, needing to add the attachment to the Client / Folder then finding the entityUuid of the Comment, Annotation, etc to add the attachments blobId to.
Postman Collection
You can test the above methods of uploading Attachments using the linked Postman collection below. The collection covers authentication as well as retrieving a Configurator or Product and uploading an Attachment to them. To run it as a collection, simply deselect any endpoints you don’t want to run, and ensure the collections global variables are set in the Pre-request Script of the collection itself. To run the endpoints individually, make sure each endpoints X-AUTH-TOKEN variable is activated in the headers and enter the necessary information to each endpoint. For more information on our Postman collections, visit this guide.