Reference Data Guide

This guide explains how to use the Reference Data API to access standardized master data in the Trace One platform.

❓ What is the Reference Data API?

The Reference Data API provides access to master data used across Trace One applications, ensuring consistency in data such as allergens, nutrients, countries, packaging types, and more.

🧭 Reference Lists vs. Functional Lists

Trace One organizes reference data into two broad types: Reference Lists and Functional Lists. Understanding the difference is key when integrating against the API.

🔹 Reference Lists (Generic Lists)

Reference Lists are generic, reusable sets of values that are often:

• Configurable by retailer or customer
• Tied to specific specification templates
• Used for UI dropdowns, filters, and form fields

These lists are retrieved via the /lists/{listName} endpoints.

Retailers may customize these lists to reflect their business rules, terminology, or data model.

🔹 Functional Lists (Domain-Specific Lists)

Functional Lists represent business-critical master data with standardized semantics defined by Trace One. These are tightly coupled with the PLM domain and often relate to product formulation, labeling, compliance, or regulatory processes.

Examples include:

• Nutrients (/nutrients)
• Allergen definitions (/allergens)
• Harmonized trade codes (/harmonized-codes)
• Markets and fishing zones

These lists are not typically configurable by the customer and reflect Trace One's domain model.

🔹 What types of reference data are available?

The API includes access to:

• Reference Lists
  e.g., preservation-method, storage-condition-temperature, trade-item-status, languages, etc.

• Allergens
  List of known allergens and their classifications.

• Countries & Country Divisions
  ISO country data and regional breakdowns.

• Fishing Zones
  Official geographic zones for seafood sourcing.

• Harmonized Codes
  HS codes used in trade and compliance.

• Markets
  Trace One-defined market definitions.

• Nutrients & Nutrient Families
  Structured nutrient definitions and their groupings.

• Raw Materials
  Classification items and parts used in formulations.

• Substances & Substance Functions
  Chemical or additive data used in product specifications.

🔹 How do I get all items from a reference list?

Use this endpoint to retrieve all items in a specific list:

\ GET /api/v2/lists/{listName} \\

Example:

\ GET /api/v2/lists/preservation-method?languageCode=en-US \\

Optional query parameters:

• languageCode – ISO language code (e.g., en-US, fr-FR)
• companyId – If applicable, for company-specific values

🔹 How do I get a specific item by ID?

Use this endpoint:

\ GET /api/v2/lists/{listName}/{itemId} \\

Example:

\ GET /api/v2/lists/languages/123e4567-e89b-12d3-a456-426614174000 \\

🔹 Do I need authentication?

Yes, all Reference Data endpoints require a Bearer token. Include the token in your request headers:

\ Authorization: Bearer your-access-token \\

🔹 What response should I expect if the item doesn't exist?

You will receive a 404 Not Found response if:

• The itemId does not exist in the list
• The item lacks a translation in the requested language

🔹 Can I get results in other languages?

Yes. Use the languageCode query parameter to get translated values.

Example:

\ GET /api/v2/lists/trade-item-status?languageCode=fr-FR \\

For more details, refer to the API Reference or contact devsupport@traceone.com.