Skip to main content

​
Step-by-Step Implementation

1

Create Service Request

When an item sells and is ready for authentication, create a draft service request to get started. This provides you with the specific image requirements for the selected item category.API Reference: POST /api/v2/srRequired Headers:
const headers = {
  'x-api-key': 'leo_xxxxxxxxx',                // Your actor API key
  'x-user-token': 'lm_usr_a1b2c3d4e5f6',      // User's secure token
  'Content-Type': 'application/json'
};
Request Data:
  • Reference ID: Your internal item identifier
  • Service UUID: Selected from available authentication services
  • Item Taxonomy: Category and type UUIDs from your taxonomy mapping
Dependencies:
2

Get Image Requirements

Retrieve the specific image sides required for your item category. This tells you exactly which photos to capture during the listing process.API Reference: GET /api/v2/sr/{sr_uuid}/side-groupsPath Parameters:
  • sr_uuid - Service request UUID
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

Secure Image Upload

Upload your pre-captured images using Legitmark’s secure CDN system.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
  3. Verify upload using progress tracking endpoint
Upload Flow Example:
// Step 3a: Get upload URL using the media service intent endpoint
const uploadUrlResponse = await fetch(
  `https://media.legitmark.com/intent?sr=${srUuid}&side=${sideUuid}.jpg`
);
const { url: presignedUrl } = await uploadUrlResponse.json();

// Step 3b: Upload binary data
const uploadResponse = await fetch(presignedUrl, {
  method: 'PUT',
  body: imageFile,
  headers: { 'Content-Type': 'image/jpeg' }
});

// Step 3c: Verify upload success
if (uploadResponse.ok) {
  console.log('Image uploaded successfully');
}
4

Validate Requirements

Before finalizing, check that all requirements are satisfied by tracking upload progress.API Reference: GET /api/side-groups/progressQuery Parameters:
  • sr_id - Service request UUID to check progress
Validation Checks:
  • All required images uploaded: No missing required sides
  • Image quality meets standards: Clear, focused, adequate lighting
  • Item information complete: All taxonomy and service data provided
  • Service request ready for processing: Meets submission criteria
Response Indicators:
{
  "success": true,
  "progress": {
    "current_required": 2,
    "total_required": 2,
    "current_optional": 1,
    "total_optional": 3,
    "met": true
  },
  "last_updated": "2024-01-01T00:00:00.000Z"
}
5

Finalize for Authentication

Once validation passes, submit your service request for expert authentication.Note: The finalization endpoint details are provided during actor onboarding. This step triggers the Quality Control and Authentication workflow.Post-Finalization Process:
  1. Quality Control Review: Initial image and data verification
  2. Authentication Review: Expert authentication by specialists
  3. Results Notification: Webhook updates for completion or issues

​
Implementation Patterns

​
Error Handling

async function createServiceRequest(itemData) {
  try {
    const response = await fetch('/api/v2/sr', {
      method: 'POST',
      headers,
      body: JSON.stringify(itemData)
    });

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

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

​
Progress Tracking

class AuthenticationProgress {
  constructor(srUuid) {
    this.srUuid = srUuid;
    this.steps = {
      created: false,
      requirements_fetched: false,
      images_uploaded: false,
      validated: false,
      finalized: false
    };
  }

  async checkProgress() {
    const response = await fetch(`/api/side-groups/progress?sr_id=${this.srUuid}`, {
      headers
    });
    const data = await response.json();
    
    this.steps.validated = data.progress.met;
    return this.steps;
  }
}

​
Batch Image Upload

async function uploadAllImages(srUuid, imageFiles) {
  const uploadPromises = imageFiles.map(async ({ sideUuid, file }) => {
    // Get upload URL
    const uploadUrlResponse = await fetch(
      `https://media.legitmark.com/intent?sr=${srUuid}&side=${sideUuid}.jpg`
    );
    const { url } = await uploadUrlResponse.json();

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

  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

​
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
  3. Upload test images
  4. Validate completion

​
Monitor Upload Status

Check upload completion using the progress tracking endpoint: API Reference: GET /api/side-groups/progress

​
Next Steps

Once workflow implementation is complete:
  1. Setup Webhooks - Webhook notifications and status update handling
  2. Test end-to-end workflow with sample items
  3. Monitor authentication processing and success rates