Legitmark API Platform Documentation

Overview

Legitmark uses a four-level hierarchical classification system. Each level determines authentication requirements and service selection: 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 - GET /api/v2/categories/tree

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();

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`);
}

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.

Key filtering endpoints

Get Brands for Type - GET /api/v2/types/{type_uuid}/brands
Get Models for Brand

Additional endpoints

List Brands - GET /api/v2/brands
Get Types for Category
List Categories - GET /api/v2/categories
Get Single Category
List Types
Get Single Type
List Models

Integration approaches

Use our taxonomy directly

Present Legitmark categories to your users:

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.
});

const { data: categories } = await legitmark.taxonomy.getCategories();

for (const category of categories) {
  console.log(category.name);
}

Get brands for a selected type

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

const { data: brands } = await legitmark.taxonomy.getBrandsForType(typeUuid);

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

Map your existing categories

Translate your platform’s categories to ours:

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:

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

Setup your Workflow - Step-by-step process from service request creation to image upload
Learn about States - Service request states and workflow transitions

Subscribe to real-time events - Webhook notifications and status update handling

Quick reference

Interactive API reference - Test all endpoints with live authentication and detailed specifications

​Overview

​Getting taxonomy data

​Complete tree

​Key filtering endpoints

​Additional endpoints

​Integration approaches

​Use our taxonomy directly

​Get brands for a selected type

​Map your existing categories

​Caching

​Next steps

​Quick reference

Overview

Getting taxonomy data

Complete tree

Key filtering endpoints

Additional endpoints

Integration approaches

Use our taxonomy directly

Get brands for a selected type

Map your existing categories

Caching

Next steps

Quick reference