Toplist API

What this is, and isn't

This is a reference document only: endpoints, authentication, response shapes, the geo resolution algorithm your integration must implement, and the compliance reasoning behind it.

• No SDK or package is provided. DataFlair does not ship a client library in any language. You build your own HTTP client against the plain-JSON contract described in this section.
• No live "resolve my visitor's geo" endpoint exists. DataFlair does not evaluate your visitor's location for you on a per-request basis. See Integration model.
• Every code sample in this section is either curl (a raw HTTP request) or plain pseudocode (the resolution algorithm), never tied to a specific implementation language.

Base URL and scoping

Base URL: https://{your-tenant-domain}. The domain of the request resolves your tenant only. The site your data is scoped to is a separate, finer-grained resolution: it comes from the site_id baked into the credential you authenticated with, not from the hostname. Changing which domain you call does not change which site's toplists you get back. That's determined entirely by which credential you used. Your DataFlair account contact will give you the exact domain and credentials for your integration.

Endpoints

All endpoints below (except the auth exchange) require the Authorization: Bearer header and are rate-limited per-credential, default 60 requests/minute (your specific credential may be configured with a different limit: check with your DataFlair contact if you're unsure).

Method	Path	Requires scope	Purpose
POST	/api/v1/auth/token	none (key+secret)	Exchange credentials for a bearer token. See Auth token endpoint
GET	/api/v1/toplists	toplist:read	List toplists, optionally filtered. See Toplists endpoints
GET	/api/v1/toplists/by-slug/{slug}	toplist:read	Fetch one toplist by its slug
GET	/api/v1/toplists/{id}	toplist:read	Fetch one toplist by its numeric ID
GET	/api/v1/brands	brand:read	List every active brand in the tenant. See Brands endpoint

API versions (v1 vs v2)

Everything documented in this section is v1 (/api/v1/...), the recommended surface for a new integration. A v2 (/api/v2/...) also exists. Its brand shape is genuinely additive on top of v1: every v1 brand field name is unchanged, with ~15 new multi-vertical fields appended (sports betting fields like sportsCovered / hasLiveBetting / hasBetBuilder, poker fields like pokerVariants / pokerNetwork, and sweepstakes-casino fields like hasSweepsCoins / scToUsdRate).

Its offer shape is not additive. It's a rename. The offer embedded inside a v2 toplist item uses different camelCase field names than either v1 offer shape, not just different casing: for example wageringRequirement (not bonusWageringRequirement as in v1's /api/v1/brands, and not bonus_wagering_requirement as in v1's toplist-embedded offer). A parser written against either v1 offer shape will silently get missing/null fields if pointed at a v2 response instead of an error. Don't assume v2's offer fields are a superset of v1's. The geo object and the outer toplist/item envelope (ids, position, template, site, etc.) are identical between the two versions. The two sub-objects that do differ are brand (additive) and offer (renamed). Don't assume only one of them changed.

Use v2 instead of v1 only if you specifically need one of those multi-vertical fields. One practical heads-up if you do: v2's single-toplist lookups (/api/v2/toplists/{id} and /api/v2/toplists/by-slug/{slug}) are currently missing the same "must have a live edition" gate that v1's equivalents and both versions' GET /toplists listing apply. A toplist with no live edition, one that correctly never appears in GET /api/v2/toplists (or any v1 endpoint) and correctly 404s on v1's single-item lookups, can still come back as a 200 from v2's single-item lookup, just with an empty items array and no currentPeriod, instead of the 404 you'd get everywhere else. Don't treat a 200 from a v2 single-item lookup as proof a toplist is genuinely live; if you need that guarantee, check the index() listing (either version) or use v1's single-item endpoints instead. This is a known internal inconsistency, not intended behavior. Flag it to your DataFlair contact if you hit it.

Non-goals

• No SDK, package, or generated client is provided in any language.
• No live per-request geo-resolution endpoint exists. You always fetch ahead and resolve locally (see Integration model).
• This section does not cover DataFlair's admin UI or internal editing workflows: only the read-only external API surface documented here.