Getting started

A minimal path to your first successful API call.

1. Get a credential

DataFlair issues API credentials out of band. There's no self-service signup. Your DataFlair account contact will give you either a static bearer token, or a key + secret pair, along with the domain your integration should call. See Authentication for what each option means and which one to pick.

For a periodic background-sync integration (the common case, see Integration model), the static token is the simpler starting point: no exchange call, no expiry to manage.

2. Make your first request

The example below calls the Toplist API, the only API module in DataFlair.ai today. Other integration surfaces, such as Stats postbacks and the Marketplace Ad Server API, have their own authentication and errors, described under their products.

Every authenticated request carries your token the same way, and should always send Accept: application/json:

curl "https://{your-tenant-domain}/api/v1/toplists?template_id=55" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

template_id scopes the request to one geo family: every toplist built from the same template, one row per market/country plus an optional global variant. See Toplists endpoints for the full parameter reference and Geo-targeting & compliance for what to do with the geo object on each row you get back.

3. Handle errors

A wrong or missing credential, a missing scope, and rate limiting all return a consistent JSON error shape. See Error handling for the full reference table before you write your error-handling code.

Next steps

• Brands endpoint: look up the full brand catalog directly, for example by ID, independent of any specific toplist.
• Integration model: why there's no live "resolve my visitor" endpoint, and what your integration needs to do instead.
• Geo-targeting & compliance: the resolution algorithm you must implement before rendering anything sourced from this API.