SokoGrow API for developers

Organisations get API keys with scopes and signed webhooks for their members' orders and listings. Test against the sandbox with fc_test_ keys before going live.

Download the OpenAPI 3.1 document · Create an API key in SokoGrow

Org-scoped access to listings, your members' orders and usage, plus signed webhooks. Authenticate with `X-Api-Key: fc_live_…` (production) or `fc_test_…` (the sandbox on staging). Money is always an integer string in minor units. Every key has scopes and a per-minute limit; every call is metered.

Endpoints

• GET /v1/api/listings listings:read
  Search live listings · q, lang, pillar, categoryId, country, currency, minPrice, maxPrice, practice, near, radiusKm, verification, sort, page, perPage
• GET /v1/api/listings/{id} listings:read
  One live listing · id*
• GET /v1/api/orders orders:read
  Orders your organisation's members are party to · status, since, limit
• GET /v1/api/orders/{id} orders:read
  One order · id*
• GET /v1/api/usage usage:read
  This month's metered usage · period
• GET /v1/api/data/{code} data:read
  A data product (aggregates only; cells under 10 people or 10 deals are withheld) · code*, country*, from*, to*, category, region
• GET /v1/api/webhooks webhooks:manage
  List webhook endpoints
• POST /v1/api/webhooks webhooks:manage
  Add a webhook endpoint (the signing secret is returned once)
• DELETE /v1/api/webhooks/{id} webhooks:manage
  Disable an endpoint · id*
• POST /v1/api/webhooks/{id}/test webhooks:manage
  Send a signed `ping` now · id*
• GET /v1/api/webhooks/{id}/deliveries webhooks:manage
  Delivery log (attempts, status codes, errors) · id*

Webhooks and signatures

POSTed as JSON `{ id, type, createdAt, data }`. Verify `X-SokoGrow-Signature: t=<unix>,v1=<hex>` as HMAC-SHA256 of `<t>.<raw body>` with your endpoint secret, and reject timestamps older than 5 minutes. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. Deliveries can repeat: deduplicate by `id`. The same values are also sent under the legacy `X-FarmChat-*` header names for integrations built before the rename.

• order.created
• order.accepted
• order.funded
• order.in_transit
• order.delivered
• order.completed
• order.cancelled
• order.refunded
• order.disputed
• listing.published
• listing.updated
• listing.deleted
• ping