---
url: https://docs.dataflair.ai/guide/getting-started.md
description: The shortest path to a first successful call to the DataFlair Toplist API.
---

# 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](/guide/authentication) for what each
option means and which one to pick.

For a periodic background-sync integration (the common case, see
[Integration model](/dataflair/toplist-api/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`:

```bash
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](/dataflair/toplist-api/toplists-endpoint) for the full parameter reference and
[Geo-targeting & compliance](/dataflair/toplist-api/geo-targeting) 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](/guide/error-handling) for the full reference table before you write
your error-handling code.

## Next steps

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