FAQ: Content Experience Suite API

General Questions

Q: What can I do with the Content Experience Suite API?

A: The Platform API is a rest API to facilitate:
• Creating and updating product records
• Publishing core marketing content to recipients
• Uploading assets, downloading assets
• Linking of assets to attribute values
• Creating recipient overrides
• Setting taxonomy
• Linking recipients
• Creating package hierarchies
• Search and retrieval of product records from the product index or from the marketplace
• Progression of workflow steps
• Checking data quality and readiness for publication by recipient*
• Checking post-publication feedback*

*Please note that these are restricted functions. They are not available to customers who have a competitor involved in their integration.

Q: What can I NOT do with the Content Experience Suite API?

A: The Platform API does NOT provide means to create Enhanced Content nor does it provide access to reporting. For enhanced content automation, you will need to learn more about our Batch Content XML process. For retrieving analytics reports, you will want our Report Builder API documentation. Please reach out to your account representative for documentation and information on Batch XML and Report Builder API.

The Platform API is a Rest API. It does not take any action without the customer system triggering it. It cannot consume files that do not conform to the Content Experience Suite API format requirements. It also cannot consume files from your system on a schedule. Any scheduling needs will need to be managed on the customer system side.

While the API can be used to search and retrieve product records, it cannot be used to retrieve only the content published to a single recipient in a single instance. The product search returns a full product record that includes all data associated to that product. To retrieve the exact data published to a single recipient, it is best to use the product download feature within the UI.

Q: What should I expect after I have implemented the platform API? What are the necessary maintenance considerations?

A: After implementing the Syndigo Platform API to push product data to Content Experience Suite, you should plan to have intermittent updates as recipients update their requirements. Recipients control over the content they wish to receive from suppliers and can make updates at any time. Most updates occur at the category level. You will need to have a resource or team that can make updates to the attribution sent in via API as these changes come across. Having users in the UI can help manage recipient changes while the technical team makes any necessary updates.

Q: What can/should I do in UAT Vs PROD?

A: In UAT, you can prepare your connections, create test products, and validate attributes up to publication. You may publish to a test recipient in UAT; however, it will not reach the external recipient. Our UAT environment is not integrated with our recipient partners’. Full publication to recipient must be performed in production.

Please note that requirements sets and recipient GUIDs may differ between UAT and Prod. These should be reviewed for any differences once in production.

Q: I receive timeouts when making requests in the UAT environment, what is happening?

The resources allocated to the UAT environment are drastically lower than what exists in our Production Environment.
It is not possible to publish as many products to UAT as to production.

We recommend using the UAT environment ONLY for testing purposes and checking payload structures.

Q: What are the endpoints that we can use for making API requests?

A: Here are 3 endpoints used when making API requests:

1. Production environment - https://api.syndigo.com/
2. UAT environment - https://api.uat.syndigo.com/
3. Asset storage - https://assets.syndigo.com

Q: What is the payload size limitation? How many items can be added at once for product import?

A: You can import one or many products within a single product import call. The payload size is not limited; however, it is recommended to keep it under 200 products in one call. Best practice is to keep your product import call smaller. This improves processing times and facilitates easier troubleshooting when needed.

Q: How many products can be exported using a single API search call?

A: Due to limitations of the elastic search keep the number of searched products below 10 000. Search results that yield counts >10,000 products should be filtered to be less than 10,000. This can be controlled using skip and take parameters in the product search call. Alternatively, you can use date filters to reduce the number of products in a response. It is best practice to keep the take per call small for best performance and easier troubleshooting. Use an asynchronous parallel/threading approach.

Q: What is the file size limit for assets?

A: Asset files, independent of type, have a hard limit of 1 GB

Q: Can I submit my files by FTP?

A: Yes, but FTP Ingest is a different process than using the Syndigo Platform API. Speak to your Syndigo account team for additional information on our FTP Ingest process.

Q: Can I schedule a product updates or publications?

A: Customers will need to manage the necessary code to schedule product updates and publications. These actions will take place at the time the API call is made.

Authorization/Access

Q: How do I get my username and secret?

A: You must have an existing Content Experience Suite account and API access enabled. Only users on the account flagged as Administrator can see the API credentials. For your security, we do not share Username and Secret by email. These must be obtained using the following steps with the UI. Navigate to your User Profile, select My Account, select desired account, select API Credentials.

Q: I keep getting “401 Unauthorized”? What am I doing wrong?

A: For the GET version of the call, ensure that your auth is URL encoded. Make sure your auth is current. Confirm with your Implementation Manager/CSM/AE that you have the correct account access enabled.

You can also use the POST version of the authentication method which moves the parameters into the body of the request to avoid URL encoding issues.

Q: How do I find my dataOwnerID/Company ID?

A: Data Owner ID and Company ID are the same identifier. The fastest way to locate this information in your account is within the UI.

User Profile> My Account> if you have access to multiple accounts, select desired account> API Settings

Customer Vocab

Q: Do I need a customer vocabulary?

A: Yes. The importexport endpoint is built using the customer vocabulary to translate attribute GUIDs to meaningful aliases. You will need to have a customer vocabulary created to make use of this API endpoint. When creating aliases, you can use the Syndigo attribute name as it appears in the UI or provide your own attribute value.

Q: How do I create my customer vocab?

A: The Syndigo platform includes a Customer Managed Vocabularies (CMV) tool which you can use to build and maintain a Customer Vocab based on your desired recipients and category attribution. For more complex aliases such as Nutrition Panel and Recipient aliasing you will need to engage your Implementation Manager or account representative. Your customer vocabulary is represented by unique ID which is required in almost all API Calls.

Q: How do I find my customer vocab?

A: Your customer vocab is located in your account under:
configurations>company settings>vocabularies
By default the vocab ID is the name of the vocab, but this name can be changed to anything. To see the Vocab ID in the URL, select a vocab using the checkbox, click 'edit' and the ID can be seen in the URL.

Supplier Activities

GDSN & Product Hierarchy

Q: Why won’t my GDSN publication go through?

A: Do you have multiple versions of the same GTIN? For GDSN publications, every product must have a catalog registration. Only one catalog registration can exist for a given GTIN + GLN + Target Market. If you have two records with the same GTIN, one will be missing the catalog registration and will not be able to successfully publish.

Q: How do I create product hierarchy?

A: Parent product must be created first. Then child products can be imported and linked within the product import call using the “ImmediateParentDetails” information to note parent and quantity of current product contained in the parent. Child records know their parents but parents don’t know their children. Declaration of product hierarchy is performed within the child product.

Q: How to view a desired identifier type for a packaging hierarchy?

A: The packaging hierarchy is located under the attribute "ImmediateParentDetails".
To view actual identifiers for the packaging hierarchy, make sure the "ProductIdentifierProperty": "" is set to your desired identifier type** in a vocabulary.
Remember that the identifier type (e.g. GTIN, UPC) needs to be mapped in the vocabulary first!

Q: Can my product be a part of multiple hierarchies?

A: Yes, a child product can belong to more than one parent. To do so by API, this must be declared within the “ImmediateParentDetails” section of the child product import/update call. Note that this must be declared holistically as all contents of the ImmediateParentDetail section are replaced at any given time that information is sent.

Q: Where do I put my product hierarchy information? Where do I put details about the case, pallet, and each?

A: Each level of the product hierarchy exists as a separate record in the Content Experience Suite.

Q: How can I get a flattened hierarchy?

A: You will need custom attribution to capture flattened hierarchy information. Discuss with your account representative. This may warrant separating into a different account if you are also capturing standard GDSN product hierarchy.

Q: What are all the ‘Party’ ID names, what do they mean and how do I find the IDs if required?

A: "Party" is just a distinction of a "location". From the GDSN world, location is point of origin and/or destination. So, a company can have 10 different loading docks in a country - each would have a GLN to identify that location for shipping needs. Or manufacturers can have 3 different facilities and GLN might specify which one is producing which product.

Q: Where can I find the sourceParty ID?

A: It can be found in the platform, in the party settings:

Additional GDSN information

GDSN is GTIN based. You must use GTIN as your product identifier for GDSN publications. GTIN must be unique to a single product record. GDSN assumes that all modifications will happen on the same product record throughout the life of the product. Archiving live product GTINs to and making a new record will break the associated GDSN registration.

Importing Products

Q: How do I find the taxonomy node identifier?

A: You will need to ask your Syndigo account team for the top-level taxonomy node for each recipient you are trying to reach via API. Once you have the top-level node, you can use the taxonomy calls to explore the children and find the identifier for the category you need.

Q: Where can I find the product’s GUID?

A: It can be found on the address bar in your browser.

Q: How do I find Recipient IDs?

A: This can be found two ways, within the UI or by calling the product search call on a product that is already linked to the desired recipient. In the UI under the Recipients tab, select the desired recipient. Once on that recipient page, note the URL. The Recipient Id is the alpha numeric string in the URL after “recipient/” and before “/profile”, ...recipient//profile.

Alternatively, if you have a product that has already been linked to the recipient, you can find the Recipient Id’s in the “RecipientsToLink” section of the response payload (if you don't see them, please include a request parameter shouldIncludeMissingVocabularyAttributes = true)

Q: How do I link my assets to a recipient?

A: A supplier cannot link their asset to a recipient but can publish the product to the recipient thus getting a copy of the asset to the recipient. Link your asset to your product by assigning the asset to the attribute and then link your product to a recipient. If you want a specific asset to go only to a specific recipient, you may want to use a recipient override.

Q: How does the Content Experience Suite manage assets?

A: Upon initial asset upload (URL or binary), the platform downloads and saves a copy of the asset file to our DAM. Publications to recipients create another copy of the asset for use by the recipient in the platform. GDSN recipients receive a URL that points back to our DAM. The recipient can then download the asset using the URL.

Q: How do I search/check for Assets?

A: It can be done by going into the platform and selecting the Assets tab. There is also an API asset search request that can be used for searching assets. Remember that a product search request will also provide you with assets linked to the product.

Q: How do I import my Assets? (Different methods & best practice)

A: You can import assets using the UI or via API. Using the API, you can import assets while creating/updating a product by providing assets URL in the “AssetValues” attribute. The second method is to upload the asset binary file in a request body.

If there is a need to upload thousands of assets into the platform, it is recommended to use FTP ingestion or put them into a .zip file and upload using the UI.

Q: What is the best way to know if an asset has changed on a product?

A: Seeing if the asset GUID changes for a given attribute.

Q: Why won’t my asset upload?

A: It may be because the image file is too large, or its files extension is not supported.

Q: How do I add a Recipient to my account?

A: When using the API you do not need to add Recipients to your account as you do in the UI.

Q: How can I remove a Recipient from my account?

A: This must be done via the UI.

Q: How do I Link a Recipient to my products?

A: You can do that in 2 ways, using an API import call with the attribute "RecipientsToLink" or using the UI as shown in the screenshot below.

Q: Is it reliable to assume if the filename is the same on two assets with different ids that they are the same asset image?

A: Not really. Content Experience Suite would allow to make a whole bunch of different images that all have the name "myFile.jpg" in a given company's asset library.

Q: Why won’t my product import work?

A: The product import payload must include at least one attribute to process successfully. If you are trying to link to a Recipient, set Taxonomy, or set Package Hierarchy, make sure you include at least a single attribute in the payload.

Q: How do I add/link a Product Category to my products?

A: It can be done using the UI or by specifying the taxonomy ID in the attribute "TaxonomyNodes" within a request body of a product update request.

Q: How do I create/update/import a product?

A: You can do that by using an API update call from our online documentation. From there you can specify if you want to create, update or CreateOrUpdate (it will create a product or update the existing one). You can also do that using the UI by simply creating a new product and filling in the necessary attributes.

Q: What does my Data Quality response mean, how do I read it and what actions do I need to take?

A: Data Quality checks your products for any missing or incorrectly provided data that needs to be changed. If your product is at 100% readiness score that means, it’s ready to publish.

Q: What do the different publication statuses mean and what action is needed?

A: There are 11 publication statuses that inform you about the current state of a product.
Below you can find more details about them:

1. Not Published - Not yet published,
2. Publishing - Publish in progress,
3. PendingSupplierAction - Waiting for publish on a supplier action,
4. PublishedAwaitingSubscription - Published and waiting for a subscription,
5. PendingRecipientAction - Waiting for publish on a recipient action,
6. PublishedAwaitingResponse - Published and waiting for a response,
7. Synchronized - Publish complete,
8. Error - Publish could not be completed due to error,
9. WithdrawCorrection - Publication was withdrawn. This notifies the recipient that product type or its hierarchy is changing,
10. WithdrawDelete - Publication was withdrawn for purposes of deleting. This notifies the recipient that the product will be removed from circulation,
11. Rejected - Publication was rejected by recipient.