---
title: "Getting started"
url: "https://docs.teleflows.io/guides/getting-started.md"
canonical_url: "https://docs.teleflows.io/guides/getting-started/"
last_updated: 2026-10-06
type: tutorial
summary: "Create an API key, authenticate with the X-API-Key header and page through lists."
related:
  - "https://docs.teleflows.io/guides/api-keys.md"
---

# Getting started

1. Open **Settings → API keys** and create a key.
2. Choose its role and an expiry within one year. Only roles whose permissions fit within your own are available.
3. Copy the key and save it securely. You can only see the full key once.
4. Set `TELEFLOWS_API_KEY` in your environment, then send a request:

   ```sh
   curl "https://api.teleflows.io/api/v2/campaigns?page=1&page_size=20" \
     -H "X-API-Key: $TELEFLOWS_API_KEY"
   ```

More about keys, roles, expiry and revoking: [API Keys](https://docs.teleflows.io/guides/api-keys/).

## Public campaign offers

Browse published campaign offers without an API key or login:

```sh
curl "https://api.teleflows.io/api/v2/public/campaign-offers?page=1&page_size=20"
```

The JSON response lists each campaign's ID, name, country and
`estimated_payout_per_call` range (`min`, `max`, `currency`). Amounts are decimal
strings. No organization parameter is needed. Filter with `search` or a two-letter
uppercase `country_code`. Page size is at most 100 and page number is at most 1000.

Estimates describe publisher earnings per incoming call, including unpaid calls.
By default, they use seven days of mature history, refresh once per day and show
a range 25% either side of the historical average. Fewer than 30 calls produce a
wider 50% range. Missing history or negative total payouts return a null range. Campaign eligibility is checked on each request. Individual publisher
terms can differ; the range is an estimate rather than a guaranteed rate.

This endpoint accepts JSON only and has a separate anonymous request limit. Follow
`Retry-After` on a 429 response. Account endpoints below still require an API key.

## Authentication and access

Send your key in the `X-API-Key` header. These endpoints support GET requests only. Do not add a Bearer token. Your key can only read records allowed by both your current role and its assigned role. Use the paths in the [API reference](https://docs.teleflows.io/api-reference/) for integrations.

To rotate a key, create a replacement, update your integration, then revoke the old key in Settings. Expired and revoked keys cannot make requests.

## Pagination and dates

Entity lists accept `page` (starting at 1) and `page_size` (up to 100). Responses include `items`, `total`, `page`, `page_size` and `pages`. Continue until you reach the last page. Available filters are listed on each endpoint. Timestamps use ISO 8601 with a timezone offset.

## Errors and limits

| Status | What to do |
|---|---|
| 401 | Check your key, expiry and revocation status. |
| 403 | Your key cannot perform this operation. |
| 404 | The resource does not exist or is outside your access. |
| 405 | Use the documented GET method. |
| 422 | Correct the parameter identified in the response. |
| 429 | Wait for the `Retry-After` duration before retrying. Your API keys share an API request allowance that is separate from your browser activity. |
| 503 | A required service is temporarily unavailable; retry later. |

## Try a request

Open an endpoint in the [API reference](https://docs.teleflows.io/api-reference/), enter your API key and select **Test Request**. The request goes directly to your API. Your key is kept in that page's memory; it is not saved between visits.
