Copy page

LegitGrails API

Integration setup

Use this guide for the decisions shared by every integration. Endpoint schemas and less common cases are covered in the API Reference and linked guides.

1. Create an API key

API keys are available and managed at account.legitgrails.com/settings/integrations. Create a Test or Live key for your integration and give it only the scopes your service needs. The key determines the environment; both environments use the same base URL:

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

Scope	Use it for
orders:write	Catalog reads, photo uploads, order creation, and requested-photo submissions
orders:read	Catalog reads, order lists, and order details
balance:read	Credit balance reads
webhooks:manage	Webhook endpoint management
audit:read	Account audit-event reads

An order-processing service usually needs orders:write and orders:read. Keep keys in a server-side secret manager; never expose them in browser or mobile code.

2. Authenticate

Send the API key as a bearer token on every request:

Code
Authorization: Bearer YOUR_API_KEY

Make an authenticated catalog request:

Code
curl --fail-with-body --silent --show-error \
  "https://api.legitgrails.com/v1/integrations/catalog/categories" \
  --header "Authorization: Bearer $LEGITGRAILS_API_KEY"

See Authentication for environment rules, rotation, and authentication errors.

3. Resolve catalog codes

Resolve the current order context instead of hard-coding names or photo requirements:

1. Select a category_code from GET /catalog/categories.
2. Select a compatible brand_code from GET /catalog/brands.
3. If needed, select a model_code from GET /catalog/models.
4. Select an available answer_time from GET /catalog/answer_times.
5. Load GET /catalog/photo_indexes with the selected category, brand, and optional model.

Send the numeric code of an answer time whose available value is true. See Catalog for query parameters, localization, and pagination.

4. Prepare photos

POST /orders accepts photo URLs issued by POST /photos. For each catalog photo index:

• include a photo when required is true;
• use its exact code as photos[].index_code;
• stay within photo_limit; and
• keep the URL reachable while the order is processed.

Upload images to POST /photos, check each result's status, and use URLs only from uploaded results. File types, upload limits, and the requested-photo flow are documented in Photos.

5. Create an order

Send one item per POST /orders request and persist the returned id. You can also supply external_id to correlate the order with your own records.

With a Test key, include mock_outcome as authentic, fake, unable-to-verify, or update-photos. The order is created immediately in the corresponding simulated state. Omit mock_outcome when using a Live key.

Order creation can return 402 when the account lacks credits. The Quickstart shows a complete request, and Orders covers the available request and response fields.

6. Track orders

Read GET /orders/{id} using the returned order ID until the order is finished:

Status	Action
queued or processing	Poll again later.
update-photos	Resolve every current photos_to_resubmit entry, then keep tracking.
completed	Process outcome and any optional result fields.
error	Stop polling and investigate or contact support with the order ID.

An order can request photos more than once, so always use the latest order detail. GET /orders can reconcile active work in batches. The error state does not produce an order-outcome webhook, so polling or scheduled reconciliation must detect it.

Webhooks provide order-outcome and update-photos notifications. Keep polling or scheduled reconciliation to recover missed deliveries. Authenticate HMAC or OAuth2 deliveries and process duplicate delivery IDs idempotently; see Webhooks.

Live readiness checklist

• Replace the Test API key with a Live API key, remove mock_outcome, and keep the same base URL.
• Keep keys server-side, minimally scoped, and out of logs.
• Refresh catalog codes, available answer times, and photo requirements.
• Persist the LegitGrails order id.
• Handle 402, 429, and other HTTP errors, retaining their request_id; see Rate limits for the current per-category limits.
• Support repeated update-photos rounds.
• Authenticate and deduplicate webhooks, with polling reconciliation for missed events.

Review the API Reference before enabling live traffic.