Legitmark API Platform Documentation

Overview

Service requests use a two-part state system:

Primary state: Main stage (DRAFT → QC → UNDERWAY → COMPLETE)
Supplement state: Additional context (PENDING, APPROVED, REJECTED, etc.)

State combinations

Primary State	Supplement State	Description	Partner Action
`DRAFT`	-	Just created, missing requirements	Complete payment/images
`QC`	`PENDING`	Queued for quality control review	Wait for review
`QC`	`REJECTED`	Photos failed quality check	Re-upload the rejected sides, then `POST /resubmit`
`QC`	`APPROVED`	Quality control passed	Wait for authentication
`QC`	`COMPLETE`	Fast-track completion during QC	Check final results
`UNDERWAY`	`PENDING`	Ready for authentication assignment	Wait for assignment
`UNDERWAY`	`ASSIGNED`	Authenticator assigned and working	Wait for completion
`UNDERWAY`	`APPROVED`	Authentication process completed	Wait for final results
`COMPLETE`	`APPROVED`	Authentic - Item verified genuine	Authentication passed
`COMPLETE`	`REJECTED`	Not authentic - Item is counterfeit	Authentication failed
`COMPLETE`	`COMPLETE`	Fully processed with documentation	Authentication completed
`CANCELLED`	-	Service request cancelled	Request cancelled

Workflow

Key states to handle

State	Action required
`QC + REJECTED`	Re-upload the rejected photos, then `POST /api/v2/sr/{uuid}/resubmit`
`COMPLETE + APPROVED`	Authentication passed - Item verified as authentic
`COMPLETE + REJECTED`	Authentication failed - Item is not authentic
`CANCELLED`	Request cancelled - Service request was cancelled

Implementation

// Essential state handling
function handleServiceRequestUpdate(sr) {
  if (sr.state.primary === 'QC' && sr.state.supplement === 'REJECTED') {
    showAttentionRequired(sr); // Partner action needed
  }
  
  if (sr.state.primary === 'COMPLETE') {
    if (sr.state.supplement === 'APPROVED') {
      handleAuthentic(sr); // Authentication passed
    } else {
      handleNotAuthentic(sr); // Authentication failed
    }
  }
}

Photo retake

QC / REJECTED means quality control asked for new photos. Upload a replacement for each rejected side, then call POST /api/v2/sr/{sr_uuid}/resubmit. That returns the service request to QC / PENDING. POST /api/v2/sr/{sr_uuid}/submit applies while the service request is DRAFT. From QC / REJECTED it returns 400.

Webhooks

Real-time updates are available via webhooks:

state_change - Any state transition
media_rejected - Images need fixes
invalidate_sr - Request cancelled

See webhook events for complete details.

​Overview

​State combinations

​Workflow

​Key states to handle

​Implementation

​Photo retake

​Webhooks