Legitmark API Platform Documentation

Step-by-Step Implementation

Create Service Request

When an item is ready for authentication, create a service request. This provides you with the specific image requirements for the selected item category.API Reference: POST /api/v2/srRequired Headers:

const headers = {
  'Authorization': 'Bearer leo_xxxxxxxxx',      // Your API key
  'Content-Type': 'application/json'
};

Request Data:

Service UUID (optional): Your partner service identifier. If omitted, auto-resolved based on your organization and item type.
Item Taxonomy: Category, type, and brand UUIDs from your taxonomy mapping
External ID (optional): Your internal item identifier for correlation

const response = await fetch('https://api.legitmark.com/api/v2/sr', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    // service is optional — auto-resolved if omitted
    external_id: 'your-internal-ref-123',
    item: {
      category: 'category-uuid',
      type: 'type-uuid',
      brand: 'brand-uuid',
    }
  })
});

const { sr } = await legitmark.sr.create({
  // service is optional — auto-resolved if omitted
  external_id: 'your-internal-ref-123',
  item: {
    category: 'category-uuid',
    type: 'type-uuid',
    brand: 'brand-uuid',
  },
});

Dependencies:

Taxonomy mapping configured (see Taxonomy)

Get Image Requirements

Retrieve the specific image sides required for your item category. This tells you exactly which photos to capture.API Reference: GET /api/v2/sr/{sr_uuid} with query parametersFetch the service request with requirements=true and sides=true to get the full image requirements:

const response = await fetch(
  `https://api.legitmark.com/api/v2/sr/${srUuid}?requirements=true&sides=true&item=true`,
  { headers }
);
const { sr } = await response.json();

// sr.requirements contains side_groups with required/optional sides
for (const group of sr.requirements.side_groups) {
  for (const side of group.sides) {
    console.log(`${side.name}: ${side.required ? 'required' : 'optional'}`);
  }
}

const { sr } = await legitmark.sr.getWithRequirements(srUuid);

console.log(`Required photos: ${sr.requirements?.total_required}`);

for (const group of sr.requirements?.side_groups || []) {
  for (const side of group.sides) {
    console.log(`${side.name}: ${side.required ? 'required' : 'optional'}`);
  }
}

Response Data:

Side groups - Organized image requirements by group
Required sides - Mandatory images for authentication
Optional sides - Additional images that enhance authentication
Template images - Visual guides for each required angle

Image Requirements:

Format: JPG/JPEG/PNG
Size: 600 x 600 px minimum
File Size: 5 MB maximum per image
Quality: Clear, well-lit, focused images

Upload Images

Upload images using Legitmark’s secure CDN system. For each required side, get a pre-signed URL and upload directly to S3.API Reference: Media Management endpoints

GET https://asset.legitmark.com/intent - Get pre-signed upload URL
PUT /{presigned-url} - Direct S3 upload

Upload Process:

Get upload URL with query parameters: sr (service request UUID) and side (side UUID with file extension)
Upload directly to the pre-signed S3 URL using PUT request with binary data

// Step 1: Get a pre-signed upload URL
const intentResponse = await fetch(
  `https://asset.legitmark.com/intent?sr=${srUuid}&side=${sideUuid}.jpg`,
  { headers }
);
const { url: presignedUrl } = await intentResponse.json();

// Step 2: Upload binary image data to the pre-signed URL
await fetch(presignedUrl, {
  method: 'PUT',
  body: imageFile,
  headers: { 'Content-Type': 'image/jpeg' }
});

// Upload from file path
await legitmark.images.uploadForSide(srUuid, sideUuid, './photo.jpg');

// Or from buffer
await legitmark.images.uploadForSide(srUuid, sideUuid, imageBuffer);

Check Progress

Verify that all required images have been uploaded before submitting.Fetch the service request with sides=true to get the current progress, which includes counts of uploaded required and optional images:

const response = await fetch(
  `https://api.legitmark.com/api/v2/sr/${srUuid}?sides=true`,
  { headers }
);
const { sr } = await response.json();

const progress = sr.sides.progress;
console.log(`Uploaded: ${progress.current_required}/${progress.total_required}`);
console.log(`Ready to submit: ${progress.met}`);

const progress = await legitmark.sr.getProgress(srUuid);

console.log(`Uploaded: ${progress.current_required}/${progress.total_required}`);
console.log(`Ready to submit: ${progress.met}`);

Progress Response:

{
  "current_required": 2,
  "total_required": 2,
  "current_optional": 1,
  "total_optional": 3,
  "met": true
}

When met is true, all required images are uploaded and the service request can be submitted.

Submit for Authentication

Once progress requirements are met, submit the service request for expert authentication.API Reference: POST /api/v2/sr/{sr_uuid}/submit

const response = await fetch(
  `https://api.legitmark.com/api/v2/sr/${srUuid}/submit`,
  { method: 'POST', headers }
);
const { sr } = await response.json();
console.log(`Submitted! State: ${sr.state.primary}/${sr.state.supplement}`);

const progress = await legitmark.sr.getProgress(srUuid);

if (progress.met) {
  const { sr } = await legitmark.sr.submit(srUuid);
  console.log(`Submitted! State: ${sr.state.primary}/${sr.state.supplement}`);
}

Post-Submission Process:

Quality Control Review: Image and data verification
Authentication Review: Expert authentication by specialists
Results Notification: Webhook updates at each stage (see States)

Implementation Patterns

Error Handling

async function createServiceRequest(itemData) {
  try {
    const response = await fetch('https://api.legitmark.com/api/v2/sr', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer leo_xxxxxxxxx',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(itemData)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Service request failed: ${error.error.message}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Service request creation failed:', error);
    // Implement retry logic or user notification
  }
}

import { Legitmark, LegitmarkError, withRetry } from 'legitmark';

const legitmark = new Legitmark('leo_your_api_key');

// Built-in retry with exponential backoff
const { sr } = await withRetry(
  () => legitmark.sr.create({
    item: { category: '...', type: '...', brand: '...' },
  }),
  {
    attempts: 3,
    onRetry: (error, attempt) => console.log(`Retry ${attempt}...`),
  }
);

Batch Image Upload

async function uploadAllImages(srUuid, imageFiles) {
  const uploadPromises = imageFiles.map(async ({ sideUuid, file }) => {
    const intentResponse = await fetch(
      `https://asset.legitmark.com/intent?sr=${srUuid}&side=${sideUuid}.jpg`,
      { headers: { 'Authorization': 'Bearer leo_xxxxxxxxx' } }
    );
    const { url } = await intentResponse.json();

    return fetch(url, {
      method: 'PUT',
      body: file,
      headers: { 'Content-Type': 'image/jpeg' }
    });
  });

  const results = await Promise.allSettled(uploadPromises);
  return results.map((result, index) => ({
    sideUuid: imageFiles[index].sideUuid,
    success: result.status === 'fulfilled' && result.value.ok,
    error: result.status === 'rejected' ? result.reason : null
  }));
}

// The SDK handles intent + upload in one call
for (const { sideUuid, filePath } of imagesToUpload) {
  await legitmark.images.uploadForSide(srUuid, sideUuid, filePath);
}

Best Practices

Pre-Sale Optimization

Cache image requirements for frequently used categories
Validate images client-side before storage
Compress images while maintaining quality standards
Store images locally until item sells

Upload Optimization

Use parallel uploads for multiple images
Implement retry logic for failed uploads
Show upload progress to users
Validate upload completion before proceeding

Validation Strategy

Check requirements before finalization
Handle validation errors gracefully
Provide user feedback on missing requirements
Retry validation after corrections

TypeScript SDK

The official TypeScript SDK (npm install legitmark) handles the complete workflow with type safety, automatic retries, and a clean resource-based API:

import { Legitmark } from 'legitmark';

const legitmark = new Legitmark('leo_your_api_key');

// 1. Browse taxonomy
const { data: categories } = await legitmark.taxonomy.getTree({ activeOnly: true });

// 2. Create service request (service auto-resolved if omitted)
const { sr } = await legitmark.sr.create({
  item: { category: '...', type: '...', brand: '...' },
});

// 3. Get requirements
const { sr: srWithReqs } = await legitmark.sr.getWithRequirements(sr.uuid);

// 4. Upload images (handles intent + upload automatically)
await legitmark.images.uploadForSide(sr.uuid, sideUuid, './photo.jpg');

// 5. Check progress and submit
const progress = await legitmark.sr.getProgress(sr.uuid);
if (progress.met) {
  await legitmark.sr.submit(sr.uuid);
}

See the SDK documentation for installation, configuration, and detailed usage.

Testing and Debugging

Test Service Request Creation

Use the Interactive API Reference to test service request creation with your actual credentials.

Validate Image Upload Flow

Test the complete upload process:

Create a test service request
Fetch image requirements via GET /api/v2/sr/{uuid}?requirements=true&sides=true
Upload test images via the intent flow
Verify progress via GET /api/v2/sr/{uuid}?sides=true
Submit via POST /api/v2/sr/{uuid}/submit

Next Steps

Once workflow implementation is complete:

Setup Webhooks for real-time status notifications
Review States for handling authentication results
Test end-to-end workflow with sample items

​Step-by-Step Implementation

​Implementation Patterns

​Error Handling

​Batch Image Upload

​Best Practices

​Pre-Sale Optimization

​Upload Optimization

​Validation Strategy

​TypeScript SDK

​Testing and Debugging

​Test Service Request Creation

​Validate Image Upload Flow

​Next Steps