> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legitmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Taxonomy

> Item classification system for accurate authentication requirements.

## Overview

Legitmark uses a four-level hierarchical classification system. Each level determines authentication requirements and service selection:

```mermaid theme={null}
graph TD
    A["Category<br/><small>Top-level classification</small>"] --> B1["Bags"]
    A --> B2["Watches"]
    
    B1 --> C1["Tote Bags"]
    B1 --> C2["Clutch Bags"]
    B2 --> C3["Luxury Watches"]
    B2 --> C4["Sports Watches"]
    
    C1 --> D1["Louis Vuitton"]
    C1 --> D2["Chanel"]
    C3 --> D3["Rolex"]
    C3 --> D4["Louis Vuitton"]
    
    D1 --> E1["Neverfull MM"]
    D1 --> E2["Speedy 30"]
    D3 --> E3["Submariner"]
    D4 --> E4["Tambour"]
    
    style A fill:#e1f5fe
    style B1 fill:#f3e5f5
    style B2 fill:#f3e5f5
    style C1 fill:#fff3e0
    style C2 fill:#fff3e0
    style C3 fill:#fff3e0
    style C4 fill:#fff3e0
    style D1 fill:#e8f5e8
    style D2 fill:#e8f5e8
    style D3 fill:#e8f5e8
    style D4 fill:#e8f5e8
    style E1 fill:#fce4ec
    style E2 fill:#fce4ec
    style E3 fill:#fce4ec
    style E4 fill:#fce4ec
```

**Hierarchy Levels:**

* **Level 1: Category** (Required) - Broad product classification
* **Level 2: Type** (Required) - Specific product subcategory
* **Level 3: Brand** (Optional) - Manufacturer or designer
* **Level 4: Model** (Optional) - Specific product variant

## Getting taxonomy data

### Complete tree

Get everything in one request for initial setup:

**API Reference:** [Get Taxonomy Tree](/api-reference/categories/get-taxonomy-tree) - `GET /api/v2/categories/tree`

<CodeGroup>
  ```javascript HTTP theme={null}
  const response = await fetch('https://api.legitmark.com/api/v2/categories/tree?active_only=true', {
    headers: { 'Authorization': 'Bearer leo_xxxxxxxxx' }
  });
  const { data: categories, metadata } = await response.json();
  ```

  ```typescript SDK theme={null}
  const { data: categories, metadata } = await legitmark.taxonomy.getTree({ activeOnly: true });

  console.log(`${metadata.total_categories} categories, ${metadata.total_types} types`);
  for (const category of categories) {
    console.log(`${category.name}: ${category.types?.length} types`);
  }
  ```
</CodeGroup>

<Tip>
  The taxonomy tree includes category and type (required), plus brand and model (optional). **Matching on brand and model is highly recommended** to get more specific image requirements based on full taxonomy depth. If brand and model are not matched, there may be additional photos required for authentication.
</Tip>

### Key filtering endpoints

* [Get Brands for Type](/api-reference/types/get-brands-for-type) - `GET /api/v2/types/{type_uuid}/brands`
* [Get Models for Brand](/api-reference/brands/get-models-for-brand)

### Additional endpoints

* [List Brands](/api-reference/brands/list-brands) - `GET /api/v2/brands`
* [Get Types for Category](/api-reference/categories/get-types-for-category)
* [List Categories](/api-reference/categories/list-categories) - `GET /api/v2/categories`
* [Get Single Category](/api-reference/categories/get-single-category)
* [List Types](/api-reference/types/list-types)
* [Get Single Type](/api-reference/types/get-single-type)
* [List Models](/api-reference/models/list-models)

## Integration approaches

### Use our taxonomy directly

Present Legitmark categories to your users:

<CodeGroup>
  ```javascript HTTP theme={null}
  const response = await fetch('https://api.legitmark.com/api/v2/categories?active_only=true', {
    headers: { 'Authorization': 'Bearer leo_xxxxxxxxx' }
  });
  const { data } = await response.json();

  data.forEach(category => {
    console.log(category.name); // "Bags", "Shoes", etc.
  });
  ```

  ```typescript SDK theme={null}
  const { data: categories } = await legitmark.taxonomy.getCategories();

  for (const category of categories) {
    console.log(category.name);
  }
  ```
</CodeGroup>

### Get brands for a selected type

<CodeGroup>
  ```javascript HTTP theme={null}
  const response = await fetch(
    `https://api.legitmark.com/api/v2/types/${typeUuid}/brands`,
    { headers: { 'Authorization': 'Bearer leo_xxxxxxxxx' } }
  );
  const { data: brands } = await response.json();
  ```

  ```typescript SDK theme={null}
  const { data: brands } = await legitmark.taxonomy.getBrandsForType(typeUuid);

  for (const brand of brands) {
    console.log(`${brand.name} (${brand.uuid})`);
  }
  ```
</CodeGroup>

### Map your existing categories

Translate your platform's categories to ours:

```javascript theme={null}
const categoryMap = {
  "Designer Handbags": "bags-category-uuid",
  "Athletic Shoes": "shoes-category-uuid"
};

function getLegitmarkCategory(yourCategory) {
  return categoryMap[yourCategory];
}
```

## Caching

Cache taxonomy data to improve performance. The taxonomy catalog changes over time as new brands and categories are added, so regular synchronization is important:

```javascript theme={null}
class TaxonomyCache {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.data = null;
    this.lastFetch = null;
  }

  async getTree() {
    const maxAge = 24 * 60 * 60 * 1000; // 24 hours
    
    if (this.data && Date.now() - this.lastFetch < maxAge) {
      return this.data;
    }

    const response = await fetch('https://api.legitmark.com/api/v2/categories/tree?active_only=true', {
      headers: { 'Authorization': `Bearer ${this.apiKey}` }
    });
    
    this.data = await response.json();
    this.lastFetch = Date.now();
    
    return this.data;
  }
}
```

Sync daily to capture new categories, brands, and models as they're added to the platform.

## Next steps

1. [Setup your Workflow](/partner/workflow) - Step-by-step process from service request creation to image upload
2. [Learn about States](/partner/service-request-states) - Service request states and workflow transitions

* [Subscribe to real-time events](/webhook-reference/introduction) - Webhook notifications and status update handling

### Quick reference

* [Interactive API reference](/api-reference) - Test all endpoints with live authentication and detailed specifications