VNTANA Logo - White
Book A Call

Resources

API – Searching for Products

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.

The VNTANA Platform offers a variety of parameters for the Product’s you create which allow for these Product’s to be retrieved via searches both on the Platform and via the API. These parameters include but are not limited to Attributes, Tags, and Conversion Status.

When searching via the API, the process is the same with the only difference being the parameters passed in the Request Body. Before making a request to the Product Search endpoint, you must be properly authenticated. View this guide to see a more detailed explanation of the steps required to authenticate .

  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.

Once authenticated, a call must be made to the following endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Method: POST
Endpoint: /v1/products/clients/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
‘page’ : 1,
‘size’ : 10,
‘clientUuids’ : [ ‘some-client-uuid’ ],
‘searchTerm’ : ‘string’,
‘organizationUuid’ : ‘some-org-uuid’,
‘tagsUuids’ : [],
‘tagName’ : ‘string’,
‘attributeKey’ : ‘string’,
‘attributeValue’ : ‘string’
}

All searches made on the VNTANA Platform and via the API use a fuzzy search concept. This means that the results returned are sorted by relevance, with the most relevant results being returned first. The parameters page and size are required parameters which indicate how to paginate the results, meaning

1
2
3
4
{
‘page’ : 1,
‘size’ : 10
}

will return the first page of results at 10 products per page. From here the other search parameters can be used to filter or sort the results.

The full possible Request Body for Product searches is as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
“attributeKey” : “”,
“attributeValue” : “”,
“clientUuids” : [],
“conversionStatuses” : [],
“description” : “”,
“locationName” : “”,
“locationsUuids” : [],
“name” : “”,
“organizationUuid” : “”,
“page” : 1,
“size” : 10,
“searchTerm” : “”,
“sorts” : {},
“status” : [],
“tagName” : “”,
“tagsUuids” : [],
“variantGroupName” : “”,
“variantGroupUuids” : []
}

Search Products by Attribute

One parameter which can be used to sort the results of a search are Attributes. Attributes are directly tied to the Product for which they are applied. Multiple products can have the same Attribute key and value pair, but a single Product can only have the same Attribute key once.

There are a couple key notes to keep in mind with this search method. Only one Attribute can be used per search request, and if the Attribute key or value have a space in them it will not work. These issues can be partially circumvented by making use of the searchTerm parameter, multiple terms can be included into this separated by spaces and it will attempt to find products which match as many of the words in any way possible. The Attribute search parameter is slated to be updated to remove the existing restrictions.

1
2
3
4
5
6
7
{
‘attributeKey’ : ‘string’,
‘attributeValue’ : ‘string’,
‘clientUuids’ : [],
‘page’ : 1,
‘size’ : 100
}

Search Products by Tags

Tags can also be used to filter the results of a search. Unlike Attributes which are directly tied to the Product they are applied to, Tags are actually tied to the Client / Folder in which they are created. Multiple Client’s / Folder’s can have the same Tag, but they are unique Tags with separate UUID’s meaning when searching for a Tag, unless you are searching all Client’s / Folder’s that could contain that Tag Name, you will not see the all possible results. Unless you only wish to check a single Client / Folder, it is best practice when looking for specific Tags to simply search the entire Organization.

Tag UUID's

When searching by Tag UUID’s you will have to pass along a list of all Tag UUID’s you wish to include.

1
2
3
4
5
6
{
‘clientUuids’ : [],
‘page’ : 1,
‘size’ : 100,
‘tagsUuids’ : [ ‘some-tag-1’, ‘some-tag-2’ ]
}

These UUID’s can either be stored locally, or you can retrieve a list of Tags and use the UUID’s you retrieve in your Product search request.

To retrieve a list of Tags use the following endpoint:
1
2
3
4
5
6
7
8
9
Method: POST
Endpoint: /v1/tags/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘clientUuid’ : ‘some-client-uuid’,
‘page’ : 1,
‘size’ : 10,
‘searchTerm’ : ‘string’
}
The UUID’s of the Tag(s) you wish to utilize can be pulled from the response, structured as such:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 2,
“grid”: [
{
“uuid”: “some-tag-uuid-1”,
“name”: “Some Tag 1”
},
{
“uuid”: “some-tag-uuid-2”,
“name”: “Some Tag 2”
}
]
}
}

When searching with Tag UUID’s, only products that contain at least one of the included Tag’s will be returned, with the results being sorted based on any other criteria you may include.

Tag Names

Searching by Tag Name is more limited than searching by Tag UUID, but does not require the additional step of retrieving these UUID’s (if not already known). The tagName can take multiple terms separated with a space, and like with Attributes, you can add more by adding Tags to the searchTerm parameter. In addition to not needing the UUID’s already, with this method you can get more results as the search will return Products that are deemed relevant, even if the tagName doesn’t completely match a certain Product’s Tag name.

Search Products by Conversion Status

Another useful Product parameter to search by is conversionStatus. This refers to the Conversion Status of a Product, or where in the Optimization process the Product is. This can be used to check when a newly created product has completed its conversion or simply automating the process of retrieving Product’s as they finish converting after uploading in bulk. Generally we would recommend using our Webhook’s to subscribe to Product Conversion events to be automatically notified when this happens, but if a Webhook’s solution doesn’t work for your integration, then you can simply make the Search API calls. You can view the Webhook’s guide here.

A list of the Conversion Statuses that can be retrieved and their Webhook Event equivalent for reference.
Processing Status API Response Webhook Event
Uploading NO_ASSET product.added
Pending PENDING product.pending
Processing CONVERTING product.processing
Completed COMPLETED product.complete
Terminated TERMINATED product.terminated
Failed FAILED product.failed

Postman Collections

Below are a couple Postman collections for testing Product searches.

The Search Product collection is a general purpose search collection, for you to enter the various search Parameters allowed for the endpoint.

The Search Product by Tag UUID’s collection is specifically used for searching by Tag UUID’s which requires an extra endpoint. Of course, you could have these UUID’s stored locally and skip that step, but incase you do not, this will show you how to handle it.

You can view a guide on using our Postman collections here but generally you can either enter the necessary global variables for the whole collection and run the collection as a whole (need to choose which type of authentication to use, key or email / pass) or run each individually and enter the data as needed. To run them separately, you’ll need to activate the deactivated headers for each endpoint.

Search Product Collection

Postman

Search Product by Tag UUID’s Collection

Postman

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.
Learn More

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

OK