Getting Started

Ready to integrate with Trustana? This guide will walk you through your first API integration, from authentication to understanding your account configuration.

Prerequisites

Before you begin, ensure you have:

• ✨ Trustana Account: Active account with API access
• ✨ API Key: Generated from the Portal's API Key Management section
• ✨ Development Environment: Your preferred programming language and tools
• ✨ System Integration Plan: Understanding of how Trustana will map to your existing systems

Authentication

All API requests require your API key in the X-API-Key header:

curl -X POST https://api.trustana.com/v1/attributes/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

API Key Management

• Portal Access: Generate API keys through Portal > API Key Management
• Key Limits: Up to 5 active keys per account
• Key Control: Portal users can activate/deactivate keys as needed, or delete them. Changes in key statuses take between 30 seconds to 1 minute.
• Team Coordination: Coordinate with Portal admin to receive a team invite, so you get access to key management

Base URLs

• Production: https://api.trustana.com/v1
• Sandbox: Available upon request (see Sandbox section below)

Sandbox Environment

Sandbox accounts are available upon request to your Customer Success Representative. Sandbox environments may not mirror the production environment exactly and are intended for development and testing purposes.

To Request Sandbox Access:

• Contact your Customer Success Representative
• Specify your development timeline and testing requirements
• Receive separate sandbox credentials and endpoint URLs

Integration Overview

Since enrichment cannot be triggered by API, your integration focuses on:

1. Account Configuration Discovery: Get attributes and category nodes configured by your Portal users
2. System Mapping: Map Trustana configuration to your existing systems
3. Media Management: Build image uploading and ID association mechanisms
4. Product Data Integration: Implement product CRUD operations aligned with your account setup

Integration Planning

Configuration Discovery

Use the first steps above to:

• Map Attributes: Understand which attributes exist and their data types
• Category Structure: Learn the category hierarchy for proper product classification
• Existing Patterns: Analyze current products to understand data patterns

System Mapping

• Attribute Mapping: Map Trustana attributes to your system's fields
• Category Alignment: Align category structures between systems
• Data Transformation: Plan data format conversions and validation rules

Media Management

• Image Upload: Implement media upload workflows using the Uploading Media guide
• ID Association: Track media IDs and associate them with products
• Storage Strategy: Plan how to manage media references in your system

Suggested First Steps

Start by exploring your account configuration to understand how Portal users have set up categories and attributes:

✨ Step 1: Get All Account Attributes

curl -X POST https://api.trustana.com/v1/attributes/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {},
    "pagination": {
      "limit": 50,
      "offset": 0
    },
    "sort": {
      "field": "createdAt",
      "order": "DESC"
    }
  }'

Advanced Filtering Options:

curl -X POST https://api.trustana.com/v1/attributes/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "option": { 
        "variantable": { "$exists": false } 
      },
      "key": {"$eq": "basicInfoTags"}
    },
    "pagination": {
      "limit": 100,
      "offset": 0
    },
    "sort": {
      "field": "createdAt",
      "order": "DESC"
    }
  }'

Filter Options:

• option.variantable: {"$exists": false}: Find non-variant-specific attributes
• key: {"$eq": "basicInfoTags"}: Search for specific attribute by key
• Use pagination and sorting to manage large attribute sets

This reveals all attributes configured in your account, their types, and category associations.

✨ Step 2: Get Category Taxonomy

curl -X GET https://api.trustana.com/v1/taxonomies \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Sample Response:

{
  "errorCode": 0,
  "data": {
    "tree": [
      {
        "id": "1",
        "name": "Beauty",
        "description": "",
        "children": [
          {
            "id": "13",
            "name": "Fragrance",
            "description": "",
            "children": [
              {
                "id": "14",
                "name": "Home Fragrance",
                "description": "",
                "children": [],
                "createdAt": 1733209515173
              }
            ],
            "createdAt": 1733209515173
          }
        ],
        "createdAt": 1733209515173
      },
      {
        "id": "2",
        "name": "Electronics",
        "description": "",
        "children": [
          {
            "id": "15",
            "name": "Mobile Devices",
            "description": "",
            "children": [
              {
                "id": "16",
                "name": "Smartphones",
                "description": "",
                "children": [],
                "createdAt": 1733209515173
              }
            ],
            "createdAt": 1733209515173
          }
        ],
        "createdAt": 1733209515173
      }
    ]
  }
}

This shows the complete category hierarchy structure configured by your Portal users.

✨ Step 3: Get Existing Products

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {},
    "pagination": {
      "limit": 50,
      "offset": 0
    },
    "sort": {
      "field": "updatedAt",
      "order": "DESC"
    }
  }'

This helps you understand existing product structure and attribute usage patterns by retrieving all products in your catalog.