# 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](/apis/) or contact [devsupport@traceone.com](mailto:devsupport@traceone.com).