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 workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace.
Getting Started
Using the VNTANA Admin API automating the full process of Showroom integration is possible, including the creation, publishing, and sharing of Showrooms. When creating or updating a Showroom, you can designate asset groupings, add images and style to the showroom, remove assets, and add organization level Showroom tags.
As with all endpoints in the VNTANA Admin API, you must first properly authenticate, generating a Refresh Token as below. View this guide for a more complete look at authentication.
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 Workspaces and store the needed UUID.
Pass the x-auth-token in the Request Headers.
This step can be skipped if the Workspace UUID is already stored locally.
Generate a Refresh Token for the Workspace (Organization Admin / Owner users must skip this step).
Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Workspace UUIDs.
12345{‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’}Returns the Refresh Token as the Response Header x-auth-token.
Showrooms
Creating / Updating a Showroom
When creating a Showroom, you will be able to define the name, groups, tagsUuids, layoutAttributes, and a logoBlobId, granting full control over the structure of the Showroom. This step does not include the creation of tags or addition of Assets as these will have to occur at different stages in the process. Note: In order for tags to be added at this step they have to have been created first to make use of their tagUuid and creation of these tags requires a unique showrooms related endpoint as they are Organization level tags as opposed to the standard Workspace level tags you apply to your Assets. More on this later.
To create a Showroom via the API you will have to call the following endpoint:
- name: This is the name of the Showroom which will be visible on the Showroom view page.
- tagsUuids: A list of tagUuid’s to be added to the Showroom. These refer to Showroom tags which are not the same as the tags applied to Assets.
- logoBlobId: the blobId of an already uploaded image to be used as the Showroom logo. This image can be uploaded using a special showroom specific endpoint.
- groups: You can create groupings for the assets added to the Showroom to ensure specific assets appear together.
- layoutAttributes: Certain aspects of the pages style have been opened up and can be set with this object. More on this below.
The response from a successful showroom creation is as follows:
Groups
The groups object allows you to designate where the assets you add to the Showroom will appear. If you only pass a single group in this object then all assets will be in the order given, however if you add multiple then their order will be related to the other assets in their group, and the groups will be ordered based on the order they are passed in the object.
- title: This will be used to identify the group and will be visible above the first entry in the group (not visible in legacy version of Showroom).
- dividers: Indicate whether you would like dividers for this group. This value can be TOP or BOTTOM.
- visible: Indicate whether this group should be visible from share links or not.
- productsInfo: The individual assets to be added in this group.
- productUuid: The UUID of an asset to be added.
- visible: Indicates whether this asset should be visible from share links or not.
- order: The spot this asset should be placed in. Is specific to this group and starts at spot 1.
Layout Attributes
In addition to the overall layout of your assets in groups, you can also add some style to your Showroom.
PRODUCTS_PER_ROW: Indicates the max number of assets per row. If set to 4 but you have a group of 3 that group will be on it’s own row. Can be 3, 4, or 5.
TEXT_COLOR: Hex value of a color for the font used on the Showroom.
FONT_FAMILY: The name of a font family to use. Default is Roboto.
BACKGROUND_COLOR: Hex value to be use for the background color of the Showroom.
BACKGROUND_IMAGE_BLOB_ID: BlobId of an image to be used as the background of the Showroom. This is optional.
DIVIDER_COLOR: Hex value to be used for the color of all dividers in the Showroom.
IMAGE_STYLE: Cover, Contain, Tile
Updating a Showroom
In order to update a showroom you will call almost the same endpoint as when creating, adding the Showrooms UUID in the request body and changing to a PUT request instead of POST:
Important: Do note that when updating a Showroom, the data that is passed is the data the Showroom will contain. This means that if you intend for all or some of the Assets already contained in the Showroom to be retained you have to pass their information again in the Update call.
Retrieving Showroom Data
When needing to interact with a Showroom to either update it’s data or view certain information about it there are two methods available. If you do not already have the showroomUuid then you can do a search of all Showrooms in your Organization, or if you do have this UUID you can directly call it’s data. Of the two methods, the request by UUID will provide significantly more information, including information on the assets contained within, and as such calling both may be necessary (if the showroomUuid is not already known)
Searching Showrooms
To search a showroom you will need to call the following endpoint:
For this endpoint you simply need to pass the page of results you wish to see and how many results per page (size) the response should contain. Note: this is a v2 endpoint. This will provide a response like the following:
In this response you can find the showroomUuid (uuid) for each showroom, as well as the number of assets in each showroom and the clientUuid’s for the workspaces the included assets belong to.
Retrieving Showroom by UUID
The second method of obtaining a Showrooms details is to directly pull it by using the showroomUuid of the showroom in question. To do this call the following methd:
This will return a much more verbose response containing not only the showroom data found from a search but also data on the assets contained within. Expand below for an example response.
Showroom Tags
One of the extra parameters that can be passed to the Showroom creation endpoint is tagsUuids. This is a list containing the UUID’s of any Showroom tags you have created and wish to be associated with the new room being created. Like tags on the VNTANA Platform in general, these are great ways to filter showrooms when attempting to search either on the Platform or via the API, especially when you have a lot of showrooms. However, unlike normal tags that you apply to individual Assets or Variant Groups/Configurators, these tags are Organization level and can be seen/accessed by all Workspaces.
Through the API there are two endpoints to handle these tags: creating and searching.
Creating a Showroom Tag
When creating a Showroom tag you must simply call the following endpoint:
The refreshToken you pass in the header will determine the Organization this tag is created in, and the name will be used to determine if the tag can be created (no duplicates). A successful creation will return the following response:
The uuid can then be passed into the tagsUuids list of the showroom creation/update endpoints to add this tag to the Showroom. If you attempt to create a tag that already exists, you will instead get the following error and have to do a search for the tag to retrieve its UUID:
Unique Errors
- TAG_ALREADY_EXISTS_FOR_ORGANIZATION_AND_NAME: Indicates a showroom specific tag already exists of the same name in this Organization.
Searching Showroom Tags
To search for and retrieve the UUID of a showroom tag that already exists you can call the following endpoint:
- searchTerm: This is what the endpoint will use to determine the results that’ll be returned. The endpoint will return exact matches first, otherwise using relevance based filtering of the results.
- page: Indicates the page of results you wish to have returned. 1 is the first page.
- size: Indicates pagination of results, how many results should be returned per page.
A successful request will return the following response:
When no exact match is found or expected, you can simply iterate over the results in grid to check the name of the tag and then pass the UUID into the create/update showroom endpoint to add it to a showroom.
Showroom Images
You can upload images to be included in Showrooms. These are not inherently tied to any single Showroom, instead they are stored and you can use the blobId associated with the uploaded image to add as a Showroom logo or background image. To upload an image call the following endpoint:
The refreshToken passed will determine the Organization the image is uploaded to. You will pass the image as form-data in the request, with name “file”. Note: In Postman you will have to add “file” to the key field of the form-data. If you are having trouble passing an image from Postman check our guide on using the collections as Postman has some blocking default behavior.
If you’ve successfully uploaded an image, you will receive the following response:
The blobId can be passed in the creation/update request for a Showroom as well as can be used to re-download the image if desired (see the expandable section below for downloading a Showroom image).
In order to download an image you’ve uploaded for a showroom, you can call the following endpoint:
This will return the byte data of the image which can be saved to a file or transferred along to another location. The refreshToken is used to indicate the Organization the image is in, and the blobId passed in the endpoint indicates which image is to be downloaded.
Showroom Attributes
With Showrooms, a key feature are the Attributes. These are key : value pairs of data which are displayed under each asset in the Showroom, allowing you to show pertinent information such as MSRP, Sizes, and SKU to viewers. It is important to note these are set at the Asset level, the Showroom simply pulls all possible options from the Assets you’ve selected to be added. It may be necessary for you to confirm what attributes are being displayed on a showroom and to do so you can call the following endpoint:
Simply pass the showroomUuid in the URL and your refreshToken in the headers and you will receive a response like the following:
Note: This only returns the key of the attributes as it is intended to showcase which attributes are being applied and each asset can have a different value for the same key. To view individual values you will have to inspect the individual assets themselves.
Share Links
A new feature of showrooms are customer specific share links. The old version of share links remains to ensure they are still usable, but these will not display any styling or grouping. Customer specific share links will however display these settings, and can be created via the API.
Create Share Link
To create a single share link you will call the following endpoint:
You will pass the showroomUuid that the share link should be created for, as well as the customerName. This customerName does not get associated with any account, but rather acts as an identifier on the showroom managers side as to who that share link is for. Once you’ve created the share link, you can then individually invite viewers and / or editors via the Share Links tab on the Platform where you will send invites directly to their email, this cannot be done via the API.
A sample response for creating a share link is as follows:
In addition to creating a share link, you can update an existing share link. The endpoint is almost the same as the create endpoint, different only in that it will be a PUT request with the uuid of the share link added to the request body:
Unique Errors
- SHOWROOM_NOT_FOUND: Indicates the showroomUuid does not match any showroom found within the Organization tied to your refreshToken.
Retrieving Share Links
Similar to showrooms, there are two methods available to retrieve information on the share links that have been created for a particular showroom. You can do a general search in which a designated number of share links will be returned or a specific data retrieval using a shareLinkUuid.
Retrieving Share Link by UUID
Once a share link has been created, you use the uuid from its response to retrieve its data for storage. To do this, pass the uuid in as shareLinkUuid in the URL of the following endpoint:
This will return the following:
You can see how many users have access to the share link, the attributes used in the Showroom, the showroomUuid, as well as the status of the share link. Finally, included in the response is the publicLink. This is the link that invited users will use to actually access the Showroom without having to be invited to the full Organization. You can grant these users Viewer or Editor privileges, with the latter being able to change order counts. Note: Creating the Sharelink does not invite users, this currently has to be done on the platform, simply visit the Showrooms page, go to the Sharelink you created and click the ‘Add User’ icon in the Users section of the page. The Sharelink must be in the LIVE status for users to view the contents at the link.
Searching for Share Links
Using the API you can also retrieve a list of all available share links in a showroom. This will allow you to make use of the data contained, update their status, and retrieve their public links. To do this use the following endpoint:
Passing the showroomUuid in the URL of the endpoint, you can designate the number or results to be returned by indicating how you wish the results to be paginated. Page will indicate which page of results to return while size indicates how many results should be in each page. Below is an example of a response from this endpoint, it is almost identical to the retrieval by UUID endpoint, but will contain entries for each share link returned.
Getting Combined Showroom and Share Link Data
In addition to the individual methods allowing you to retrieve data on a specific Showroom or Sharelink, there is an endpoint that can be utilized to get a detailed set of data for a sharelink and the assets it shows in the showroom. To get this data you will simply need the shareLinkUuid and will call this endpoint:
This will return a detailed overview of the share link itself, the showroom, as well as the assets within. Below shows an example response.
Share Link Order Counts
Another new feature of the Showrooms is the ability for Editor users invited via a share link to add ‘Order’ counts to individual assets, the totals of which can be downloaded by the Showroom’s manager. It is possible to accomplish this via the API if you wish to implement the the Showrooms order count functionality without the UI provided by VNTANA, or wish to simply implement your own script to scrape a spreadsheet and place order counts based on the data within.
Adding an Order Count to an Asset
When an Editor user accesses their share link, they will be able to add individual order counts to the Assets within, which is then visible to the Showroom Manager. To accomplish this via the API you will have to call the following endpoint:
This will have to be done on an individual Asset basis similar to in the actual share link itself. An example response is as follows:
Special Errors:
- SHARELINK_NOT_FOUND: Indicates an incorrect shareLinkUuid passed
Get Order Count By Share Link
In addition to adding order counts to assets in a share link, you can also retrieve the order counts in the share link. This will return a complete list of assets in the share link and their current order count. To do this call the following endpoint:
A successful request will return the following response:
Postman Collection
You can download the below Postman collection to test out each of these Hotspot based interactions. The collection includes everything needed to run a chain of endpoints for Authentication and Asset search, while the Hotspot endpoints will require some manual input for the various parameters needed in these endpoints. To run any part as a collection, simply uncheck any Authentication endpoints you don’t need based on your user access (see our Authentication guide for a detailed explanation) as well as enter the Hotspot parameters you wish to pass along such as the type.
To run the endpoints individually, make sure to activate the deactivated X-AUTH-TOKEN header for each endpoint, and ensure all the necessary parameters are entered in the body or query params of each. For more information on using Postman collections, see our guide.