Legitmark API Platform Documentation

Legitmark sends three event types. Every webhook destination receives all events automatically.

state_change

Sent when a service request transitions to a new state. This is the primary event for tracking authentication progress and results.

Payload

{
  "event_type": "state_change",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "state": {
    "primary": "COMPLETE",
    "supplement": "APPROVED"
  },
  "timestamp": "2026-02-10T12:00:00.000Z"
}

Fields

string

required

Always "state_change".

string

required

Service request UUID.

string | null

Your internal item ID — the external_id you set when creating the service request.

object

required

Show state properties

string

required

Primary state of the service request.

string | null

Supplementary state detail providing additional context.

string

required

ISO 8601 timestamp of when the state change occurred.

State Transitions

The table below shows the state transitions you may receive:

`state.primary`	`state.supplement`	Meaning
`QC`	`PENDING`	Photos submitted, under quality review
`QC`	`REJECTED`	Photos failed quality review — a `media_rejected` event follows with details
`QC`	`APPROVED`	Photos passed QC, authentication starting
`UNDERWAY`	`ASSIGNED`	Authenticator assigned
`COMPLETE`	`APPROVED`	Item is authentic
`COMPLETE`	`REJECTED`	Item is not authentic

The most important transition is COMPLETE + APPROVED or COMPLETE + REJECTED — this is the final authentication result. See Service Request States for the full state machine.Using the TypeScript SDK (v0.2.0+), you can check these with isAuthentic(event) and isCounterfeit(event) instead of comparing strings manually. See Handling Webhooks.

media_rejected

Sent when uploaded images fail quality control. Each rejected image includes the side UUID and the rejection reason. Use that UUID when uploading the replacement photo.

Payload

{
  "event_type": "media_rejected",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "sides": [
    {
      "side": "ec883c70-f896-47c9-81b6-8d6ff0b5856a",
      "reason": "Image is Blurry",
      "message": "The submitted image is too blurry. Please capture a clearer photo, ensuring minimal motion for better accuracy."
    },
    {
      "side": "7b2e1c40-6a18-4d3f-9c55-1e8f0a2b4d66",
      "reason": "Insufficient Lighting",
      "message": "The lighting in the submitted image is insufficient. Please take a new photo with better lighting for improved visibility."
    }
  ],
  "timestamp": "2026-02-10T12:15:00.000Z"
}

Fields

string

required

Always "media_rejected".

string

required

Service request UUID.

string | null

Your internal item ID.

array

required

Array of rejected images with reasons.

Show sides[] properties

string

required

Side UUID. This is the same UUID returned for the side on Get SR, and the value to pass when uploading the replacement photo.

string

required

Rejection reason. These are human-readable strings from the Legitmark reasons database (e.g. "Image is Blurry", "Insufficient Lighting"). Values may change as new reasons are added.

string

Extended description with guidance for the user on how to fix the issue.

string

required

ISO 8601 timestamp.

When you receive a media_rejected event, the service request is QC / REJECTED. Upload a new photo for each entry in sides, using side as the side UUID, then call POST /api/v2/sr/{sr_uuid}/resubmit. That call moves the request back to QC / PENDING.POST /submit applies only while the service request is DRAFT. From QC / REJECTED it returns 400 with Cannot submit: Service request is not in DRAFT state.

Using the TypeScript SDK, needsResubmission(event) returns true for this event type. See Handling Webhooks.

invalidate_sr

Sent when a service request is cancelled.

Payload

{
  "event_type": "invalidate_sr",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "invalidation_reason": {
    "code": "CANCELLED",
    "message": "Unsupported Product or SKU. The product or SKU provided isn't supported under our current service guidelines."
  },
  "timestamp": "2026-02-10T14:30:00.000Z"
}

Fields

string

required

Always "invalidate_sr".

string

required

Service request UUID.

string | null

Your internal item ID.

object

required

Show invalidation_reason properties

string

required

Reason code. Currently always "CANCELLED". Additional codes may be introduced in the future.

string

required

The specific cancellation reason. Common values include:

"Unsupported Product or SKU. The product or SKU provided isn't supported under our current service guidelines."
"Unsupported Channel"
"Service Request Inactivity"
"Duplicate Service Request"
"Insufficient Product Information"
"Customer Requested Cancellation"
"Poor Image Quality or Unusable Media"

Custom free-text reasons may also appear.

string

required

ISO 8601 timestamp.

​state_change

​Payload

​Fields

​State Transitions

​media_rejected

​Payload

​Fields

​invalidate_sr

​Payload

​Fields

state_change

Payload

Fields

State Transitions

media_rejected

Payload

Fields

invalidate_sr

Payload

Fields