Resources

API – Configurators

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 hereNote: 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.

The Configurator View on the VNTANA Platform allows you to group products into one viewer. These products can be color variants of one product, or various unique products from one line. The Configurator View can be used to compare models for QA purposes, or the embed link/iframe can be used to show a single viewer on your website for all the products you wish to include.

This guide will walk you through the features of the Configurator as accessible via our API, showing you how to create, view and edit a Configurator. For more information on other aspects of the VNTANA Platform API you can view this Quick Start Guide, or for a full list of API Endpoints view this page.

Note: There is a discrepancy in how Configurators are referred to on the Platform and in the API. This feature is being built from a legacy feature of the VNTANA Platform called ‘Variants’, and as such the API Endpoints still refer to this feature as ‘Variant’.

As with all Admin API endpoints, you must first properly authenticate and generate a Refresh Token. For a more detailed look at authenticate view this guide.

  1. Log in using an Authentication Key or email / password.

    • Returns an x-auth-token in the Response Headers.

  2. 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.

  3. Generate a Refresh Token for the Organization.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      2
      3
      4
      {
      ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token
      ‘organizationUuid’ : ‘string’
      }
    • Returns the Refresh Token as the Response Header x-auth-token.

  4. 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.

  5. 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.

      1
      2
      3
      4
      5
      {
      ‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
      ‘organizationUuid’ : ‘string’,
      ‘clientUuid’ : ‘string’
      }
    • Returns the Refresh Token as the Response Header x-auth-token.

Create a Configurator

When working with Configurator’s you can either search for an existing Configurator or create one. Previously referred to as a ‘Variant Group’, in order to create a Configurator you will use the following Endpoint:

1
2
3
4
Endpoint: /v1/variant-groups
Method: POST
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘clientUuid’, ‘description’, ‘name’, ‘productsUuids’, ‘tagsUuids’
  • clientUuid: [Required] The UUID of the Client / Folder you wish to create the Configurator in.

  • description: [Optional] A description of the products included in the Configurator.

  • name: [Required] The name of the Configurator. Multiple Configurators can share the same name.

  • productsUuids: [Optional] A list of UUID’s for products to add to the Configurator. No products need to be added at creation, they can be added after the fact.

  • tagsUuids: [Optional] A list of UUID’s for tags to add to the Configurator. No tags need to be added at creation, they can be added after the fact. Note: these tags are linked to the Configurator only, not the individual products that are added to the Configurator.

This Endpoint passes parameters in the URL of the Post request and the refreshToken in the Request Headers. An example URL:

1
URL: https://api-platform.vntana.com/v1/variant-groups?clientUuid=some-client-uuid&name=Test

A successful response will return the UUID of the newly created Configurator:

1
2
3
4
5
6
{
“response” : {
“uuid” : “string”
},
“success” : true
}

Test this process using the below Postman collection. To run the collection as a whole, simply set the necessary global variables and select the endpoints you wish to use. To run the endpoints individually simply activate the deactivated headers and ensure each endpoint has the necessary data. You can view our guide on Postman collections here.

Create a Configurator Collection

Search Configurators

In order to add Products to a Configurator that has already been created, you need to have the UUID of the Configurator. You can save this locally and skip this step, but if you need to find the UUID use the following Endpoint:

1
2
3
4
5
6
7
8
9
10
11
Endpoint: /v1/variant-groups/search
Method: POST
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
‘clientUuids’ : [
‘some-client-uuid’
],
‘page’ : 1,
‘size’ : 10,
‘searchTerm’ : ‘string’
}
  • clientUuids: [Optional] A list of Client / Folder UUID’s to pull Configurator’s from.

  • page: [Required] Indicates the ‘page’ of results to be returned.

  • size: [Required] Indicates the number of results to return per page.

  • searchTerm: [Optional] Used to filter the list of returned Configurator’s.

Search Term Usage Example:

There are two Configurators, Test Configurator and Sample.

Test Configurator:

  • Includes products configurator_sample, test_product, product_1, and no tags.

Sample:

  • Includes products product_1, product_2, and the tag Test

If the searchTerm test is passed to the Endpoint, both Configurators will be returned because Test Configurator contains test in the Configurator name and Sample contains test as a tag. However, if sample is passed as the searchTerm, only the Configurator Sample, will be returned as the search Endpoint won’t detect that sample exists in one of the Product names within Test Configurator.

The results of a successful Configurator search will be structured as such:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
“success” : true,
“errors” : [],
“response” : {
“totalCount” : int,
“grid” : [
“uuid” : “string”,
“clientUuid” : “string”,
“clientSlug” : “some-client-slug”,
“name” : “string”,
“description” : “string”,
“tags” : [
{
“uuid” : “string”,
“name” : “string”
}
],
“productsUuids” : [
“some-product-uuid”, “another-product-uuid”
],
“status” : “DRAFT” or “LIVE”,
“created” : “timestamp”,
“updated” : “timestamp”
]
}
}
  • totalCount: This represents the total number of Configurator’s that matched the search criteria but does not represent the number of results returned. The size parameter passed in the Request Body determines the max number of results to be returned, so unless you know you should get the exact match first it is best to pass size large enough to get all results.
  • uuid: The UUID of the Configurator in question, used to add products.
  • name: The name of the Configurator. This does not need to be unique when creating, so there can be multiple Configurator’s with the same name.
  • productsUuids: List of products currently in the Configurator.

Any combination of parameters returned in the Response Body can be used to pull the correct Configurator from the list. This may require the use of other Endpoints before or after if choosing to use Product UUID’s to find a Configurator. See the above linked documentation to see how to search for Products.

Test this process using the below Postman collection. To run the collection as a whole, simply set the necessary global variables and select the endpoints you wish to use. To run the endpoints individually simply activate the deactivated headers and ensure each endpoint has the necessary data. You can view our guide on Postman collections here.

Search Configurators Collection

Add Product to Configurator

Finally, the a Configurator without any Products isn’t very useful. To add to a Configurator that already exists, you will need to have the Configurators UUID as well as the Product UUID you wish to add. To see how to retrieve a Product UUID, view this guide on searching Products.

1
2
3
4
Method: PUT
Endpoint: /v1/variant-groups/add-products
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘productsUuids’, ‘uuids’

You’ll notice the two query parameters are both plural. You can add multiple Products in one API call and to multiple Configurators, for both parameters the UUID’s simply need to be separated by a comma. An example URL looks like this:

1
URL: https://api-platform.vntana.com/v1/variant-groups/add-products?productsUuids=some-prod-1,some-prod-2&uuids=some-conf-1,some-conf-2

A successful request will return a list of the Configurator UUID’s that the Products were added to. To see more on Configurator API interactions view the full Admin API guide above.

Test this process using the below Postman collection. To run the collection as a whole, simply set the necessary global variables and select the endpoints you wish to use. To run the endpoints individually simply activate the deactivated headers and ensure each endpoint has the necessary data. You can view our guide on Postman collections here.

Add Product to Configurator Collection

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.