Orders

Download schema

Create, list, and inspect authenticity-check orders.

List orders

GET

https://api.legitgrails.com/v1/integrations

/orders

Bearer

Lists the account's orders, newest first. page defaults to 1 and limit defaults to 10 and can be at most 50.

List orders › query Parameters

page

integer · min: 1

One-based order result page.

Default: 1

limit

integer · min: 1 · max: 50

Requested order count. Maximum 50.

Default: 10

List orders › Responses

A page of orders.

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.

Create an order

POST

https://api.legitgrails.com/v1/integrations

/orders

Bearer

Creates an authenticity-check order from stable catalog codes and managed photo URLs returned by the photo upload endpoint. Other public or externally hosted photo URLs are rejected.

The chosen answer time must currently be available for the brand/category. Required indexes and per-index photo limits come from the photo-index catalog for the submitted brand/category/model context.

A Test API key requires mock_outcome and immediately creates the order in the corresponding completed or update-photos state. A Live API key must omit mock_outcome.

Common domain errors include answer-time-unavailable, photo-index-not-found, missing-required-photo-indexes, photo-limit-exceeded, unsupported-photo-url, and mock-outcome-required.

Create an order › Request Body

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

Create an order › Responses

Order created.

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.

POST/orders

curl https://api.legitgrails.com/v1/integrations/orders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "external_id": "listing-10442",
  "brand_code": "gucci",
  "category_code": "bag",
  "model_code": "gucci-bag-gg-marmont",
  "answer_time": 720,
  "photos": [
    {
      "url": "https://media.legitgrails.com/uploads/tusd/example-overall",
      "index_code": "overall-picture"
    },
    {
      "url": "https://media.legitgrails.com/uploads/tusd/example-serial",
      "index_code": "serial-number"
    }
  ]
}'

Example Request Body

{
  "external_id": "listing-10442",
  "brand_code": "gucci",
  "category_code": "bag",
  "model_code": "gucci-bag-gg-marmont",
  "answer_time": 720,
  "photos": [
    {
      "url": "https://media.legitgrails.com/uploads/tusd/example-overall",
      "index_code": "overall-picture"
    },
    {
      "url": "https://media.legitgrails.com/uploads/tusd/example-serial",
      "index_code": "serial-number"
    }
  ]
}

json

application/json

Example Responses

{
  "id": "6a21d480-38ac-4cc3-9c0c-bd0145b687af",
  "external_id": "listing-10442",
  "order_number": "<order-reference>",
  "status": "queued",
  "due_date": "2026-08-05T09:30:00.000Z"
}

json

application/json

Get an order

GET

https://api.legitgrails.com/v1/integrations

/orders/{id}

Bearer

Retrieves an order by its LegitGrails UUID or the external_id supplied at creation.

The response includes requested-photo details and completed-result fields when applicable. English outcome_reasons and localized outcome_reasons_locale are returned for authentic/fake outcomes; outcome_indexes is returned only for a fake outcome. Localized values fall back to English.

Get an order › path Parameters

id

string · minLength: 1 · required

LegitGrails order UUID or an external_id supplied when creating the order.

Get an order › query Parameters

locale

string · enum

Locale for *_locale fields. English is always returned separately in the corresponding non-suffixed field. Missing translations fall back to English.

Enum values:

Default: en

Get an order › Responses

Order details.

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.

Submit requested photos

POST

https://api.legitgrails.com/v1/integrations

/orders/{id}/update_photos

Bearer

Resolves the current photos_to_resubmit request for an order selected by LegitGrails UUID or external_id.

Every requested index_code must appear. For each entry, supply exactly one of url or is_unable_to_provide: true. Multiple URL entries may use the same index up to its max_photos; an unable-to-provide entry must be the sole entry for its index. Every URL must be a managed URL returned by POST /photos; other URLs are rejected.

Acceptance is reported with HTTP 202 and status: accepted.

Submit requested photos › path Parameters

id

string · minLength: 1 · required

LegitGrails order UUID or an external_id supplied when creating the order.

Submit requested photos › Request Body

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.

Submit requested photos › Responses

The complete photo-update response was accepted.

SubmitUpdatePhotosResponse

id

string · uuid · required

status

string · enum · required

Enum values:

accepted

POST/orders/{id}/update_photos

curl https://api.legitgrails.com/v1/integrations/orders/:id/update_photos \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "photos": [
    {
      "index_code": "overall-picture",
      "url": "https://media.legitgrails.com/uploads/tusd/example-replacement"
    },
    {
      "index_code": "serial-number",
      "is_unable_to_provide": true
    }
  ],
  "note": "The serial-number label is no longer attached to the item."
}'

Example Request Body

{
  "photos": [
    {
      "index_code": "overall-picture",
      "url": "https://media.legitgrails.com/uploads/tusd/example-replacement"
    },
    {
      "index_code": "serial-number",
      "is_unable_to_provide": true
    }
  ],
  "note": "The serial-number label is no longer attached to the item."
}

json

application/json

Example Responses

{
  "id": "6a21d480-38ac-4cc3-9c0c-bd0145b687af",
  "status": "accepted"
}

json

application/json

Balance Audit

List orders

GET

https://api.legitgrails.com/v1/integrations

/orders

Bearer

Lists the account's orders, newest first. page defaults to 1 and limit defaults to 10 and can be at most 50.

List orders › query Parameters

page

integer · min: 1

One-based order result page.

Default: 1

limit

integer · min: 1 · max: 50

Requested order count. Maximum 50.

Default: 10

List orders › Responses

A page of orders.

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.

Create an order

POST

https://api.legitgrails.com/v1/integrations

/orders

Bearer

Creates an authenticity-check order from stable catalog codes and managed photo URLs returned by the photo upload endpoint. Other public or externally hosted photo URLs are rejected.

A Test API key requires mock_outcome and immediately creates the order in the corresponding completed or update-photos state. A Live API key must omit mock_outcome.

Common domain errors include answer-time-unavailable, photo-index-not-found, missing-required-photo-indexes, photo-limit-exceeded, unsupported-photo-url, and mock-outcome-required.

Create an order › Request Body

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

Create an order › Responses

Order created.

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.

Get an order

GET

https://api.legitgrails.com/v1/integrations

/orders/{id}

Bearer

Retrieves an order by its LegitGrails UUID or the external_id supplied at creation.

Get an order › path Parameters

id

string · minLength: 1 · required

LegitGrails order UUID or an external_id supplied when creating the order.

Get an order › query Parameters

locale

string · enum

Locale for *_locale fields. English is always returned separately in the corresponding non-suffixed field. Missing translations fall back to English.

Enum values:

Default: en

Get an order › Responses

Order details.

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.

Submit requested photos

POST

https://api.legitgrails.com/v1/integrations

/orders/{id}/update_photos

Bearer

Resolves the current photos_to_resubmit request for an order selected by LegitGrails UUID or external_id.

Acceptance is reported with HTTP 202 and status: accepted.

Submit requested photos › path Parameters

id

string · minLength: 1 · required

LegitGrails order UUID or an external_id supplied when creating the order.

Submit requested photos › Request Body

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.

Submit requested photos › Responses

The complete photo-update response was accepted.

SubmitUpdatePhotosResponse

id

string · uuid · required

status

string · enum · required

Enum values:

accepted