Schemas

Download schema

IntegrationCode

string

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

ErrorResponse

statusCode

integer · min: 400 · max: 599 · required

HTTP status code repeated in the body.

Example: 400

code

string · required

Stable machine-readable code. Domain errors use specific codes.

Example: validation-error

message

string · required

Human-readable summary.

Example: Validation failed

object · required

Additional client-actionable context when available.

timestamp

string · required

Error timestamp.

Example: <timestamp>

path

string · required

Requested path.

Example: /v1/integrations/orders

request_id

string · uuid · required

Correlation UUID also returned in X-Request-Id.

Example: 3f241e2a-0f1c-4f6f-b0fe-b17511a47e31

RateLimitDetails

category

string · enum · required

Independent rate-limit bucket used by this operation.

Enum values:

catalog

read

create

update

upload

webhook

limit

integer · min: 1 · required

Requests allowed for this API key and category in the window.

window_seconds

integer · enum · required

Enum values:

retry_after_seconds

integer · min: 1 · required

Seconds to wait before this category can accept another request.

RateLimitErrorResponse

statusCode

integer · enum · min: 400 · max: 599 · required

HTTP status code repeated in the body.

Enum values:

429

Example: 400

code

string · enum · required

Stable machine-readable code. Domain errors use specific codes.

Enum values:

rate-limit-exceeded

Example: validation-error

message

string · enum · required

Human-readable summary.

Enum values:

Rate limit exceeded

Example: Validation failed

RateLimitDetails · required

Additional client-actionable context when available.

timestamp

string · required

Error timestamp.

Example: <timestamp>

path

string · required

Requested path.

Example: /v1/integrations/orders

request_id

string · uuid · required

Correlation UUID also returned in X-Request-Id.

Example: 3f241e2a-0f1c-4f6f-b0fe-b17511a47e31

AccountAuditEventCode

string · enum

Enum values:

auth.login.succeeded

auth.login.failed

auth.password.changed

auth.email.changed

api-key.created

api-key.renamed

api-key.revoked

webhook.created

AccountAuditActorType

string · enum

Enum values:

user

api-key

system

AccountAuditSource

string · enum

Enum values:

portal-web

mobile

integration-api

system

AccountAuditTargetType

string · enum

Enum values:

user

order

api-key

webhook

webhook-delivery

AccountAuditEvent

id

string · uuid · required

account_user_id

string · uuid · required

occurred_at

string · date-time · required

event_code

AccountAuditEventCode · enum · required

Enum values:

auth.login.succeeded

auth.login.failed

auth.password.changed

auth.email.changed

api-key.created

api-key.renamed

api-key.revoked

webhook.created

actor_type

AccountAuditActorType · enum · required

Enum values:

user

api-key

system

actor_id

string | null · uuid · required

actor_name

string · required

source

AccountAuditSource · enum · required

Enum values:

portal-web

mobile

integration-api

system

target_type

string · enum · required

Enum values:

user

order

api-key

webhook

webhook-delivery

target_id

string | null · uuid · required

ip_address

string | null · required

user_agent

string | null · required

object · required

Event-specific safe metadata; secrets and webhook URLs are omitted.

AccountAuditEventsResponse

AccountAuditEvent[] · required

page

integer · min: 1 · required

limit

integer · min: 1 · max: 100 · required

total

integer · min: 0 · required

CatalogCodeName

code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

name

string · required

English display name.

Example: Gucci

name_locale

string · required

Requested-locale display name, with English fallback.

Example: グッチ

CatalogCategory

code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

name

string · required

English display name.

Example: Gucci

name_locale

string · required

Requested-locale display name, with English fallback.

Example: グッチ

icon_url

string | null · uri · required

Category icon, or null when none is configured.

CatalogBrand

code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

name

string · required

English display name.

Example: Gucci

name_locale

string · required

Requested-locale display name, with English fallback.

Example: グッチ

CatalogCategory[] · required

Categories supported by this brand.

CatalogBrandsResponse

CatalogBrand[] · required

page

integer · min: 1 · required

limit

integer · min: 1 · max: 100 · required

total

integer · min: 0 · required

Total matching brands before pagination.

CatalogCategoriesResponse

CatalogCategory[] · required

CatalogAnswerTime

code

integer · min: 1 · required

Answer time in minutes; pass this integer as answer_time.

Example: 720

name

string · required

English display name.

Example: 12 hours

name_locale

string · required

Requested-locale name, with English fallback.

Example: 12時間

price

number · required

Current order price in credits for this account and context.

Example: 15

default

boolean · required

Whether the catalog marks this option as its default.

available

boolean · required

Whether this option can be used for a new order now.

next_available_at

string | null · date-time · required

Next expected availability, or null when not applicable/known.

CatalogAnswerTimesResponse

CatalogAnswerTime[] · required

CatalogPhotoIndex

code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

name

string · required

English display name.

Example: Gucci

name_locale

string · required

Requested-locale display name, with English fallback.

Example: グッチ

required

boolean · required

Whether at least one photo with this code is required at order creation.

photo_limit

integer · min: 1 · required

Maximum images accepted for this index.

icon_url

string | null · uri · required

example_urls

string[] · required

Example images; can be empty.

CatalogPhotoIndexesResponse

CatalogPhotoIndex[] · required

CatalogModel

code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

name

string · required

English display name.

Example: Gucci

name_locale

string · required

Requested-locale display name, with English fallback.

Example: グッチ

image_url

string | null · uri · required

Model image, or null when none is configured.

CatalogModelsResponse

CatalogModel[] · required

page

integer · min: 1 · required

limit

integer · min: 1 · max: 100 · required

total

integer · min: 0 · required

Total matching models before pagination.

PhotoUploadResult

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · status="uploaded" · requires: url, original_name
	type = object · status="failed" · requires: original_name, error

Properties for Variant 1:

UploadedPhoto

status

string · enum · required

The file uploaded successfully.

Enum values:

uploaded

url

string · uri · pattern: ^https://media\.legi… · required

Managed URL to use unchanged in a subsequent order request.

original_name

string · required

Filename supplied for the multipart part.

UploadedPhoto

status

string · enum · required

The file uploaded successfully.

Enum values:

uploaded

url

string · uri · pattern: ^https://media\.legi… · required

Managed URL to use unchanged in a subsequent order request.

original_name

string · required

Filename supplied for the multipart part.

FailedPhotoUpload

status

string · enum · required

The file could not be uploaded.

Enum values:

failed

original_name

string · required

Filename supplied for the multipart part.

object · required

BalanceResponse

availableCredits

integer · required

Available account credits. This field is camelCase by contract.

Example: 150

CreateOrderPhoto

url

string · uri · maxLength: 2048 · pattern: ^https://media\.legi… · required

Managed photo URL returned by POST /photos. Externally hosted URLs, credentials, query strings, and fragments are rejected.

Example: https://media.legitgrails.com/uploads/tusd/example-overall

index_code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

CreateOrderRequest

brand_code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

category_code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

CreateOrderPhoto[] · minItems: 1 · maxItems: 75 · required

external_id

string · maxLength: 100

Optional client-provided order reference.

Example: listing-10442

answer_time

integer · min: 1

Requested answer time in minutes from the answer-time catalog.

Example: 720

model_code

string

Optional model code within the submitted brand/category.

Example: overall-picture

mock_outcome

string · enum

Required for Test API keys and rejected for Live API keys. Selects the immediate simulated Test-order state and outcome.

Enum values:

authentic

fake

unable-to-verify

update-photos

CreateOrderStatus

string · enum

Enum values:

queued

update-photos

completed

Initial public order state.

CreateOrderResponse

id

string · uuid · required

LegitGrails order identifier.

external_id

string | null · required

Submitted alias, or null.

order_number

string | null · required

Order reference for support communication.

status

CreateOrderStatus · enum · required

Initial public order state.

Enum values:

queued

update-photos

completed

due_date

string | null · date-time · required

Expected completion time, or null when unavailable.

OrderStatus

string · enum

Enum values:

queued

processing

update-photos

completed

error

Current public order state. completed and error are terminal; an error order has no authentication outcome.

OrderListItem

id

string · uuid · required

external_id

string | null · required

order_number

string | null · required

Order reference for support communication.

status

OrderStatus · enum · required

Current public order state. completed and error are terminal; an error order has no authentication outcome.

Enum values:

queued

processing

update-photos

completed

error

outcome

string | null · enum · required

Enum values:

authentic

fake

unable-to-verify

canceled

due_date

string | null · date-time · required

updated_at

string | null · date-time · required

OrdersResponse

OrderListItem[] · required

page

integer · min: 1 · required

limit

integer · min: 1 · max: 50 · required

Number of results requested per page.

total

integer · min: 0 · required

Total matching orders before pagination.

OrderClassification

brand_code

string | null · required

category_code

string | null · required

model_code

string | null · required

model_name

string | null · required

English model name.

model_name_locale

string | null · required

Requested-locale model name with English fallback.

PhotoToResubmit

index_code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

name

string · required

English photo-index name.

name_locale

string · required

Requested-locale photo-index name with English fallback.

condition

string | null · required

Stable English condition code such as missing or unclear.

Example: missing

condition_locale

string | null · required

Localized condition label with code/English fallback, or null when no condition is named.

requirements

string[] · required

Stable requirement codes in English.

Example: ["better-lighting"]

requirements_locale

string[] · required

Localized requirement labels aligned by array index.

comment

string | null · required

Additional guidance for the requested photo, or null.

reference_photo_url

string | null · uri · required

Reference image URL, or null.

max_photos

integer · min: 1 · required

Maximum URL submissions allowed for this index in the update round.

OrderResponse

id

string · uuid · required

status

OrderStatus · enum · required

Current public order state. completed and error are terminal; an error order has no authentication outcome.

Enum values:

queued

processing

update-photos

completed

error

outcome

string | null · enum · required

Final outcome, or null before one is assigned.

Enum values:

authentic

fake

unable-to-verify

canceled

outcome_locale

string | null · required

Localized outcome label with English fallback, or null.

delayed

boolean · required

OrderClassification · required

due_date

string | null · date-time · required

updated_at

string | null · date-time · required

certificate_url

string | null · uri

Certificate URL for a completed order, when available.

outcome_reasons

string[]

English reasons, present for authentic/fake completed outcomes.

outcome_reasons_locale

string[]

Localized reasons aligned with outcome_reasons, with per-item English fallback.

outcome_indexes

IntegrationCode[]

Unique affected index codes, present only for fake outcomes.

PhotoToResubmit[] · minItems: 1

Requested photo updates for the order.

SubmitUpdatePhoto

index_code

IntegrationCode · required

Catalog code returned by the API. Use it unchanged.

Example: overall-picture

url

string · uri · maxLength: 2048 · pattern: ^https://media\.legi…

Managed replacement photo URL returned by POST /photos.

is_unable_to_provide

boolean

Set to true only when no photo can be supplied for this index.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	requires: url
	requires: is_unable_to_provide

Properties for Photo URL:

is_unable_to_provide

boolean · enum

Enum values:

SubmitUpdatePhotosRequest

SubmitUpdatePhoto[] · minItems: 1 · maxItems: 75 · required

Entries resolving every requested index. Repeated URL entries for one index are allowed up to its max_photos.

note

string · maxLength: 1000

Optional note about the submitted photos.

SubmitUpdatePhotosResponse

id

string · uuid · required

status

string · enum · required

Enum values:

accepted

WebhookEvent

string · enum

Enum values:

order-outcome

update-photos

WebhookOauthRequest

type

string · enum · required

Enum values:

oauth2

token_url

string · uri · maxLength: 2048 · pattern: ^https:// · required

Public HTTPS OAuth2 token endpoint.

client_id

string · minLength: 1 · maxLength: 255 · required

client_secret

string · minLength: 1 · maxLength: 2048 · writeOnly · required

Never returned by the API.

scope

string · maxLength: 1024

Optional space-delimited scope sent to the token endpoint.

WebhookOauthMetadata

type

string · enum · required

Enum values:

oauth2

token_url

string · uri · required

client_id

string · required

scope

string | null · required

Requested OAuth2 scope, or null when none was configured.

CreateWebhookRequest

url

string · uri · maxLength: 2048 · pattern: ^https:// · required

Publicly reachable HTTPS destination for webhook deliveries. Redirect responses are not followed.

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

name

string · maxLength: 100

Optional endpoint label.

WebhookOauthRequest

WebhookEndpoint

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

WebhookOauthMetadata · readOnly

HmacWebhookCreateResponse

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

signing_secret

string · minLength: 64 · maxLength: 64 · readOnly · pattern: ^[a-f0-9]{64}$ · required

HMAC signing secret shown only once in this creation response.

WebhookOauthMetadata · readOnly

OauthWebhookCreateResponse

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

WebhookOauthMetadata · readOnly · required

CreateWebhookResponse

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: id, api_key_id, name +4 more
	type = object · requires: id, api_key_id, name +4 more

Properties for Variant 1:

HmacWebhookCreateResponse

id

string · uuid · required

api_key_id

string · uuid · required

API key that owns this endpoint and its order subscriptions.

name

string | null · required

url

string · uri · required

events

WebhookEvent[] · minItems: 1 · maxItems: 2 · unique · required

Enum values:

order-outcome

update-photos

created_at

string · date-time · required

signing_secret

string · minLength: 64 · maxLength: 64 · readOnly · pattern: ^[a-f0-9]{64}$ · required

HMAC signing secret shown only once in this creation response.

WebhookOauthMetadata · readOnly

WebhookEnvelope

webhook_event

WebhookEvent · enum · required

Enum values:

order-outcome

update-photos

delivery_id

string · uuid · required

Stable ID for idempotent processing and retry deduplication.

external_id

string | null · required

Order alias supplied by the partner, or null.

order_number

string | null · required

Order reference for support communication.

created_at

string · date-time · required

Time the webhook was created.

OrderOutcomeWebhookPayload

webhook_event

WebhookEvent · enum · required

Enum values:

order-outcome

delivery_id

string · uuid · required

Stable ID for idempotent processing and retry deduplication.

external_id

string | null · required

Order alias supplied by the partner, or null.

order_number

string | null · required

Order reference for support communication.

created_at

string · date-time · required

Time the webhook was created.

id

string · uuid · required

status

OrderStatus · enum · required

Current public order state. completed and error are terminal; an error order has no authentication outcome.

Enum values:

completed

outcome

string | null · enum · required

Final outcome, or null before one is assigned.

Enum values:

authentic

fake

unable-to-verify

canceled

outcome_locale

string | null · required

Localized outcome label with English fallback, or null.

delayed

boolean · required

OrderClassification · required

due_date

string | null · date-time · required

updated_at

string | null · date-time · required

certificate_url

string | null · uri · required

Certificate URL for a completed order, when available.

outcome_reasons

string[]

English reasons, present for authentic/fake completed outcomes.

outcome_reasons_locale

string[]

Localized reasons aligned with outcome_reasons, with per-item English fallback.

outcome_indexes

IntegrationCode[]

Unique affected index codes, present only for fake outcomes.

PhotoToResubmit[] · minItems: 1

Requested photo updates for the order.

UpdatePhotosWebhookPayload

webhook_event

WebhookEvent · enum · required

Enum values:

update-photos

delivery_id

string · uuid · required

Stable ID for idempotent processing and retry deduplication.

external_id

string | null · required

Order alias supplied by the partner, or null.

order_number

string | null · required

Order reference for support communication.

created_at

string · date-time · required

Time the webhook was created.

id

string · uuid · required

status

OrderStatus · enum · required

Current public order state. completed and error are terminal; an error order has no authentication outcome.

Enum values:

update-photos

outcome

string | null · enum · required

Final outcome, or null before one is assigned.

Enum values:

authentic

fake

unable-to-verify

canceled

outcome_locale

string | null · required

Localized outcome label with English fallback, or null.

delayed

boolean · required

OrderClassification · required

due_date

string | null · date-time · required

updated_at

string | null · date-time · required

PhotoToResubmit[] · minItems: 1 · required

Requested photo updates for the order.

certificate_url

string | null · uri

Certificate URL for a completed order, when available.

outcome_reasons

string[]

English reasons, present for authentic/fake completed outcomes.

outcome_reasons_locale

string[]

Localized reasons aligned with outcome_reasons, with per-item English fallback.

outcome_indexes

IntegrationCode[]

Unique affected index codes, present only for fake outcomes.

WebhookPayload

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · webhook_event="order-outcome" · requires: id, status, outcome +10 more
	type = object · webhook_event="update-photos" · requires: id, status, outcome +10 more

Properties for Variant 1:

OrderOutcomeWebhookPayload

webhook_event

WebhookEvent · enum · required

Enum values:

order-outcome

delivery_id

string · uuid · required

Stable ID for idempotent processing and retry deduplication.

external_id

string | null · required

Order alias supplied by the partner, or null.

order_number

string | null · required

Order reference for support communication.

created_at

string · date-time · required

Time the webhook was created.

id

string · uuid · required

status

OrderStatus · enum · required

Current public order state. completed and error are terminal; an error order has no authentication outcome.

Enum values:

completed

outcome

string | null · enum · required

Final outcome, or null before one is assigned.

Enum values:

authentic

fake

unable-to-verify

canceled

outcome_locale

string | null · required

Localized outcome label with English fallback, or null.

delayed

boolean · required

OrderClassification · required

due_date

string | null · date-time · required

updated_at

string | null · date-time · required

certificate_url

string | null · uri · required

Certificate URL for a completed order, when available.

outcome_reasons

string[]

English reasons, present for authentic/fake completed outcomes.

outcome_reasons_locale

string[]

Localized reasons aligned with outcome_reasons, with per-item English fallback.

outcome_indexes

IntegrationCode[]

Unique affected index codes, present only for fake outcomes.

PhotoToResubmit[] · minItems: 1

Requested photo updates for the order.