4. Implementing a Product Search Request
- 9 Minutes to read
- DarkLight
4. Implementing a Product Search Request
- 9 Minutes to read
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
The Syndigo API allows you to search products in the Syndigo Marketplace (if you are licensed for Marketplace access) as well as your Product Index. Using the Syndigo API, you can pull full product records to your internal systems for populating your company's website or gathering data for internal purposes.
You can search products using different fields such as dates, IDs, and attributes. The Platform offers a variety of Search templates for various circumstances, allowing you to carry out the necessary Search operations.
In order to implement product search requests, you will need to follow the below steps.
1. Get API credentials
Before making the API requests, you MUST obtain the API credentials (Username, Secret). The credentials will allow you to generate an authentication token that is mandatory for authorizing the requests.
The API credentials are located within My Account > API Settings. See screenshots below.
After selecting API Settings, you should see the API credentials:
You must have admin permissions to see the API credentials! Make sure one of your sub-accounts is privileged to see them. If you still can't see them, reach out to your Customer Success Manager or Account Executive.
IMPORTANT!
The API credentials are different for each account and environment! Make sure to use the correct credentials for the account you are using, in the environment where it is deployed (UAT or Production)!
Once you have the API credentials, you can get the auth token. that you will need for the subsequent API calls.
2. Setup Postman
We have a postman collection of API calls that will help you make requests. Please make sure to configure your postman environment so it is easier for you to make API calls.
3. Verify and add recipients
Verify all applicable recipients are present in your account, and add any that are missing via the "ADD NEW RECIPIENT" button on the Recipients page. This process will help gather the required attributes for creating the vocabulary that we will explain in the next step.
4. Create a Vocabulary
The Vocabulary is a mapping that aliases Syndigo attribute ID's to user defined attribute names; making it easier to create and process API payloads. It is accessed through the Vocabularies page. You must create a vocabulary as shown here in order to generate a vocabulary ID, which is required for most API calls.
WARNING
The vocabulary ID will be different for each of the environments.
If you're working with PROD and UAT, you will need to manage updating the vocabularies in both environments.
If you wish to add or modify the attributes in the vocabulary, you can do that by going to Configurations > Company Settings > Vocabularies in the Platform.
It is also possible to get the entire vocabulary via API by using a GET call, and update the vocabulary using a PUT call. This method should ONLY be used for more complicated operations such as aliasing recipients or adding workflow steps (applies to recipient implementations only). The best practice is to use the Vocabularies page in the platform for creating and modifying a vocabulary.
After creating the vocabulary, you are ready to make the product search requests.
5. Make a product search request.
After the vocabulary is created, you can start making the product search requests.
The most common search uses GTIN as the attribute identifier. You can
check other examples of product search calls. using other attributes or other methods (e.g. last modified date).
Tips
- Use the parameter shouldIncludeMissingVocabularyAttributes=true to see attributes that are not mapped in the customer vocab file - they will appear as GUIDs.
- To see Recipient Overrides returned in product search, set shouldIncludeMissingVocabularyAttributes=true and useLens=false.
- Due to limitations of the elastic search, a single API call can only return up to 10,000 items. Search results that yield counts >10,000 items should be filtered as to not exceed this threshold. Use dates (e.g. Last Modified Date) or additional attributes (e.g. "Brand",) to further refine the search.
To search the products in the Product Index (PI) by GTIN, mention the following in the postman and then click Send.
POST
If you intend to search for marketplace products, you will need to use a slightly different endpoint.
POST
Note
Access to the Marketplace varies by customer licensing. If you are a 3rd party accessing Marketplace items on behalf of a customer, you may have different access to products than the account holder.
The request body and query parameters are the same for both types of product search (product search and marketplace product search) calls. See marketplace product search calls.
Query Parameters
Expand to see the parameters and description
| Parameter | Parameter Type | Data Type | Accepted Values | Description |
| vocabularyId | Recommended (Conditionally Optional) | String | GUID | If a valid companyId is provided, vocabularyId is not Required |
| companyId | Required (Conditionally Optional) | String | GUID | If a valid vocabularyId is provided, companyId is not Required |
| skipCount | Optional | Integer | >=0; (skipCount+takeCount)<10,000 | Used in combination with takeCount to paginate large numbers of product records. Quantity of records to skip before you start taking products. Whatever value is used for the takeCount, add to skipCount for the subsequent call |
| takeCount | Optional | Integer | >= 0; Max: 500 | Sets quantity of results to return at one time. Used for parsing large numbers of product records |
| useLens | Optional | Boolean | true/false | Based on target party id as contained in Post body, will return effective values only includes all values. Defaults to true. Ex. Using a recipient ID with useLens as true will return the product data applicable to that recipient |
| flattenLensedProduct | Optional | Boolean | true/false | Allows for flattening search results. Using this parameter you'll get only the recipient overrides. |
| locale | Optional | enum | ISO 639-1 standard | Stores the value passed in a language specific variant. Facilitates different values in different langugages on the same attribute. Defaults to en-US. |
| shouldIncludeMissingVocabularyAttributes | Optional | Boolean | true/false | Will determine if attributes not included in your company vocabulary will be returned in search results. Defaults to setting in customer vocabulary, else defaults to false. If set to true, attributes not in vocabulary will return with its GUID. |
You can change the param values of skipCount, takeCount,vocabularyId, vocabularyId, useLens, and locale according to your requirements.
Headers
Authorization: Specify required Auth Token in the header.
Request Parameters
Expand to see the parameters and description
| Parameter | Parameter Type | Data Type | Accepted Values | Description |
| TargetPartyAlias | Optional | String | Recipient identifier: GUID or as aliased in customer vocab | Sets the lens through which the product data is returned from search |
| OrderBy | Optional | String | Attribute GUID (Ex. Product Name, Date Created, etc.). | Sets return results order |
| Desc | Optional | Boolean | true/false | Determines sort order (ascending or descending). |
| RecipientAliases | Optional | Array of Strings | Recipients identifiers: GUIDs or as aliased in a customer vocab | Limits the search to products explicitly linked to specific recipients. |
| AttributeFilterOperator | Optional | Boolean Operator | AND/OR | Defaults to AND |
| OnHold | Optional | Boolean | true/false | Determines if the search returns OnHold products or not. |
| Archived | Optional | Boolean | true/false | Determines if the search returns Archived products or not. |
| Language | Optional | Enum | ISO 639-1 standard | Defaults to en-US. Sets the Language to be used for search |
| DataOwner | Required | String | GUID | Company ID GUID |
| ProductIds | Optional | Array of Strings | Product GUIDs | List of Products to be searched |
| IdentifierAttributes | Optional | Array of Strings | Attribute GUIDs | List of identifier types to be searched |
| Identifiers | Optional | Array of Strings | Identifier strings | Required if you are using “Identifier Attributes”. Contains the list of identifiers to find. |
| AttributeExistsFilters | Optional | Array of Strings | Attribute GUIDs | Returns products that has (does not have) desired attribute. |
| AttributeFilters | Optional | Array of Strings | Attribute GUIDs | Searches the value of attribute defined. |
| SearchType | Part of AttributeFilters | Enum | Contains - has search val within the attribute value searched Prefix, - starts with this search value Suffix, - ends with this search value Fuzzy, - Similar match (fuzzy, a char might be missing in search value for example) Search - exact match for search value | Part of AttributeFilters |
| DateFilter | Optional | Array of Strings | See example, includes: Name, Operator, Value, IncludeMissing | Array (see example). Searched date field and defined. |
| Name | Required | Enum | CreatedDate, RecordDate LastModifiedDate, DiscontinueDate, ObsolescenceDate, LastPublishedDate | Part of DateFilter |
| Operator | Required | Enum | LessThan, LessThanOrEqualTo, GreaterThan, GreaterThanOrEqualTo | Part of DateFilter |
| Value | Required | String | Commonly acceptable string representation of a date/time | Part of DateFilter |
| IncludeMissing | Required | Boolean | true/false | Part of DateFilter |
| WorkflowFilters | Optional | Array of Strings | Workflow, Statuses [] | Contains an array including “Workflow” name and “Statuses” as defined for the customer workflow. |
| Workflow | Required | String | Workflow names as aliased in Customer Vocab | Part of WorkflowFilters |
| Statuses | Required | Array of Strings | Statuses names as aliased in Customer Vocab | Part of WorkflowFilters |
| PackagingTypes | Optional | Enum | Undefined, BaseUnit, Case, Pallet, Display, Pack, Load, SetPack, MixedModule, MultiPack, PrePack, PrePack_Assortment | Used primarily for GDSN package hierarchy |
| ExcludeProductIds | Optional | String | Product GUIDs | List of products to be excluded |
Request
{
"TargetPartyAlias": "", //if you want to get recipient's overrides, put the recipient's alias or GUID here.
"OrderBy": "",
"Desc": false,
"AttributeFilterOperator": "And",
"OnHold": false,
"Archived": false,
"Language": "en-US",
"DataOwner": "{{companyId}}", //your companyID.
"IdentifierAttributes": [
"GTIN" //It can be GTIN or any other Attribute mapped in the vocabulary.
],
"Identifiers": [
"78787878787878" //It's a sample GTIN.
]
}
Response 200 OK
Keep in mind that the response payload is reusable - you can use it for updating products from the Product Index by changing values and using it in the request body of the product import call.
{
"ErrorMode": "Fail",
"DefaultLocale": "en-US",
"ProducingOperationDetails": {
"TotalHitCount": 1,
"ResultCount": 1
},
"ProductImportData": {
"ProductsToImport": [
{
"ImportMode": "Update",
"ProductIdentifierPropertyOverride": "",
"ProductReferencePropertyOverride": "",
"ProductIdentifierValue": "d283e104-897c-42f9-989b-d65c7026c92e",
"SourceParties": [],
"TaxonomyNodes": [],
"CatalogItems": [],
"PackageType": "BaseUnit",
"ImmediateParentDetails": {},
"RecipientsToLink": [
"Amazon US"
],
"RecipientsRequirementSets": {
"Amazon US": [
"Amazon Listing 2.0"
]
},
"ComplexValues": [],
"LifeCycle": {
"CreatedDate": {
"Value": "2023-04-24T21:15:22.7817613Z",
"Delete": false
}
},
"AuditInfo": {
"CreatedDate": "2023-04-24T21:15:22.7817687Z",
"LastModifiedDate": "2024-02-23T14:39:54.6546188Z"
},
"Archived": false,
"Values": [
{
"Name": "Product Name",
"ValuesByLocale": {
"en-US": "Adding Images"
},
"SourceParty": "",
"Recipient": "",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "GTIN",
"ValuesByLocale": {
"en-US": "78787878787878"
},
"SourceParty": "",
"Recipient": "",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "Short Description",
"ValuesByLocale": {
"en-US": "Short Description from API"
},
"SourceParty": "",
"Recipient": "",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "Packaging Level",
"ValuesByLocale": {
"en-US": "BASE_UNIT_OR_EACH"
},
"SourceParty": "",
"Recipient": "",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "Main Product Image",
"ValuesByLocale": {
"en-US": "d15b778e-55a4-42d5-b20d-8bedc141fbc9"
},
"SourceParty": "",
"Recipient": "",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "nutrientFormatTypeCodeReference",
"ValuesByLocale": {
"en-US": "US_FDA_NFP_2020_STANDARD_SIDE_BY_SIDE"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "ingredientStatement",
"ValuesByLocale": {
"en-US": "TEST"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "isNutrientRelevantDataProvided",
"ValuesByLocale": {
"en-US": "Y"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "organicProductPlaceOfFarmingCode",
"ValuesByLocale": {
"en-US": "EU_OR_NON_EU_AGRICULTURE"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "dietTypeDescription",
"ValuesByLocale": {
"en-US": "TEST"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "preparationInstructions",
"ValuesByLocale": {
"en-US": "TEST"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "preparationType",
"ValuesByLocale": {
"en-US": "BAKE"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "numberOfServingsPerPackage",
"ValuesByLocale": {
"en-US": "1"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "numberOfServingsPerPackageMeasurementPrecisionCode",
"ValuesByLocale": {
"en-US": "APPROXIMATELY"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "nutrientDetailNutrientValueDerivationCode",
"ValuesByLocale": {
"en-US": "ANALYTICAL"
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
}
],
"MultiValues": [
{
"Name": "servingSuggestion",
"ValuesByLocale": {
"en-US": [
"TEST"
]
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "nutritionalClaim",
"ValuesByLocale": {
"en-US": [
"TEST"
]
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "growingMethodCode",
"ValuesByLocale": {
"en-US": [
"FLY_FREE"
]
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"Name": "nutritionLabelTypeCode",
"ValuesByLocale": {
"en-US": [
"1"
]
},
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
}
],
"ContainerValues": [
{
"ParentAttribute": "Allergen Related Information",
"RowList": [
{
"Values": [],
"MultiValues": [],
"ContainerValues": [],
"AssetValues": [],
"IsExplicitNullValue": false
}
],
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"ParentAttribute": "Sub Ingredients",
"RowList": [
{
"Values": [],
"MultiValues": [],
"ContainerValues": [],
"AssetValues": [],
"IsExplicitNullValue": false
}
],
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
},
{
"ParentAttribute": "Diet Type Information",
"RowList": [
{
"Values": [],
"MultiValues": [],
"ContainerValues": [],
"AssetValues": [],
"IsExplicitNullValue": false
}
],
"SourceParty": "",
"Recipient": "949e31b4-db30-4afb-9bf6-c9494d098a17",
"Delete": false,
"IsExplicitNullValue": false
}
],
"AssetValues": [
{
"Name": "Main Product Image",
"ValuesByLocale": {
"en-US": {
"Name": "Banana.jpg",
"Url": "https://assets.uat.syndigo.com/d15b778e-55a4-42d5-b20d-8bedc141fbc9?originalFileName=true",
"SourceUrl": "https://images.unsplash.com/photo-1587132137056-bfbf0166836e",
"Format": "jpeg"
}
},
"SourceParty": "",
"Recipient": "",
"Delete": false,
"IsExplicitNullValue": false
}
],
"IsExplicitNullValue": false
}
],
"ProductIdentifierProperty": "",
"ProductReferenceProperty": "",
"Archived": false
}
}
Be sure to check our FAQ section if you have any questions!
Was this article helpful?