Legitmark API Platform Documentation

Step-by-Step Implementation

Create Service Request

When an item is ready for authentication, create a draft service request. The response returns a minimal sr object with uuid and micro_id — photo requirements are fetched in the next step.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 response.json();
const srUuid = sr.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',
  },
});
const srUuid = sr.uuid;

Response: { success, message, sr } — use sr.uuid for all subsequent calls. The external_id you send is returned on the SR and exposed as reference_id in webhooks.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 item=true and sides=true to get the photo list. Add requirements=true if you also want the validation status object:

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

// Sides arrive pre-split into required and optional lists
for (const side of sr.sides.required) {
  console.log(`${side.name} (${side.side_group_name}) — required`);
  console.log(`  ${side.description}`);
  console.log(`  Example: ${side.thumbnail_image}`);
}

for (const side of sr.sides.optional) {
  console.log(`${side.name} (${side.side_group_name}) — optional`);
}

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

console.log(`Required photos: ${sr.sides.progress.total_required}`);

for (const side of sr.sides.required) {
  console.log(`${side.name}: ${side.description}`);
}

Photo requirements live under sr.sides, not sr.requirements. The requirements object holds validation status (media_requirements, sides_requirements, item_requirements) — it does not contain the photo list.

Response Data:

sr.sides.required - Mandatory images for authentication
sr.sides.optional - Additional images that improve authentication accuracy
sr.sides.progress - Upload counts and the met flag
Per side: uuid, name, description, ordinal, required, side_group_name, and thumbnail_image / example_image / overlay_image visual guides

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.

If your organization uses the Private CDN, skip GET /intent. Call POST /api/media/signed-urls/{sr_uuid} instead — /intent writes to the public bucket.

API Reference: Media Management endpoints

GET https://asset.legitmark.com/intent - Get pre-signed upload URL (public CDN)
POST /api/media/signed-urls/{sr_uuid} - Batch pre-signed upload URLs (private CDN)
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);

Do not send your Authorization header on the PUT to the pre-signed URL. The URL is already signed, and S3 rejects the request with 400 if an Authorization header is present. Only the intent request is authenticated with your API key.

Check Progress

Verify that all required images have been uploaded before submitting.Fetch the service request with item=true&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}?item=true&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": 8,
  "exempted_required": 0,
  "total_required": 8,
  "current_optional": 0,
  "total_optional": 5,
  "met": true
}

exempted_required is the subset of current_required that was covered by a waiver rather than an uploaded photo. When met is true, every required side is accounted for 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}?item=true&sides=true&requirements=true
Upload test images via the intent flow (or Private CDN signed-urls flow)
Verify progress via GET /api/v2/sr/{uuid}?item=true&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
Follow Private CDN if your organization keeps media off the public CDN
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

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