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:
Get Taxonomy Tree - GET /api/v2/categories/tree
const response = await fetch('/api/v2/categories/tree?activeOnly=true', {
headers: { 'x-api-key': 'your-key' }
});
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
Additional endpoints
Integration approaches
Use our taxonomy directly
Present Legitmark categories to your users:
// Fetch and display categories
const { data } = await fetch('/api/v2/categories?activeOnly=true')
.then(r => r.json());
// Use in your UI
data.forEach(category => {
console.log(category.name); // "Bags", "Shoes", etc.
});
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('/api/v2/categories/tree?activeOnly=true', {
headers: { 'x-api-key': this.apiKey }
});
this.data = await response.json();
this.lastFetch = Date.now();
return this.data;
}
}
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
Quick reference
