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.

Using the Admin API, you can search for your Products that are in the Live Internal or Live Public state in order to update them, download their assets, or construct their share links/iframes. Draft Products will not be returned by search endpoints. 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 .

Authentication Steps Summary

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.
  
  1
  
  2
  
  3
  
  4
  
  {
  
  ‘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.
  
  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, there are a couple of endpoints that can be used. Depending on your access level, you may be required to use one over the other.

If you have Organization Owner / Organization Admin level access, you can use the following endpoint:

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’
}

While Organization level users can also use the following endpoint, if you only have Folder level access (Folder Admin or Content Manager) you must use the following endpoint:

Method: POST
Endpoint: /v1/products/client/{clientUuid}/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
‘page’ : 1,
‘size’ : 10,
‘searchTerm’ : ‘string’,
‘name’ : ‘string’,
‘organizationUuid’ : ‘string’
}

Note: this search endpoint does not take clientUuids in the Request Body like the previous endpoint, instead passing a single clientUuid in the URL of the request. This of course means this endpoint will only be able to search a single Folder, while the previous endpoint can search multiple.

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

{
‘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.

Important: Products which are in the Draft state on the Platform will not be returned from search endpoints. They must be in either the Live Internal or Live Public state.

Product Search Full Request Body

The full possible Request Body for Product searches is as follows:

{
“attributeKey” : “”,
“attributeValue” : “”,
“clientUuids” : [],
“conversionStatuses” : “string”,
“description” : “”,
“locationName” : “”,
“locationsUuids” : [],
“name” : “”,
“organizationUuid” : “”,
“page” : 1,
“size” : 10,
“searchTerm” : “”,
“sorts” : {},
“status” : [“LIVE_INTERNAL”, “LIVE_PUBLIC”],
“tagName” : “”,
“tagsUuids” : [],
“variantGroupName” : “”,
“variantGroupUuids” : []
}

Important: These are the same for both search endpoints with the exception that the single client search does not take a parameter clientUuids in the request body.

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.

{
‘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.

{
‘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.

Retrieve Tag UUID's Sample

To retrieve a list of Tags use the following endpoint:

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:

{
“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.

List of Conversion Statuses that can be Returned

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

Search Product by Tag UUID’s Collection

Resources