Skip to main content

​
Step-by-Step Implementation

1

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: Your partner service identifier
  • 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: 'service-uuid',
    external_id: 'your-internal-ref-123',
    item: {
      category: 'category-uuid',
      type: 'type-uuid',
      brand: 'brand-uuid',
    }
  })
});
Dependencies:
  • Taxonomy mapping configured (see Taxonomy)
2

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

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 endpointsUpload Process:
  1. Get upload URL with query parameters: sr (service request UUID) and side (side UUID with file extension)
  2. 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://media.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' }
});
4

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

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}`);
Post-Submission Process:
  1. Quality Control Review: Image and data verification
  2. Authentication Review: Expert authentication by specialists
  3. 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
  }
}

​
Batch Image Upload

async function uploadAllImages(srUuid, imageFiles) {
  const uploadPromises = imageFiles.map(async ({ sideUuid, file }) => {
    const intentResponse = await fetch(
      `https://media.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
  }));
}

​
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
const { sr } = await legitmark.sr.create({
  service: 'service-uuid',
  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:
  1. Create a test service request
  2. Fetch image requirements via GET /api/v2/sr/{uuid}?requirements=true&sides=true
  3. Upload test images via the intent flow
  4. Verify progress via GET /api/v2/sr/{uuid}?sides=true
  5. Submit via POST /api/v2/sr/{uuid}/submit

​
Next Steps

Once workflow implementation is complete:
  1. Setup Webhooks for real-time status notifications
  2. Review States for handling authentication results
  3. Test end-to-end workflow with sample items