---
title: Fraud Prevention — Data API
---

# Fraud Prevention Data API

The Data API is the server-side counterpart to the [Web SDK](./web-sdk). Use it to
pull verdicts, aggregate statistics, and export data for **billing, settlement,
and reconciliation** — the numbers advertisers and traffic providers agree on.

## Base URL

```
https://apiv1.captcha.la
```

## Authentication

All Data API requests are authenticated with your Fraud Prevention application
credentials, sent as headers:

```
X-App-Key:    YOUR_AD_APP_KEY
X-App-Secret: YOUR_AD_APP_SECRET
```

::: warning
`X-App-Secret` is **server-side only**. Never expose it to browsers, mobile apps,
or public repositories. The landing-page SDK only ever uses the public `appKey`.
:::

## Endpoints

### Fetch a verdict

Retrieve the verdict for a single visit (e.g. to reconcile a specific click).

```bash
GET /v1/bot/verdict?click_token=ct_xxx
X-App-Key: YOUR_AD_APP_KEY
X-App-Secret: YOUR_AD_APP_SECRET
```

The response `data` is a [`BotVerdict`](./verdict-reference) object:

```json
{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}
```

### Aggregated stats

Pull bucketed counts over a time range — totals, bot share, and the breakdown by
`action`/`level` — for dashboards and quality reports.

```bash
GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_AD_APP_KEY
X-App-Secret: YOUR_AD_APP_SECRET
```

```json
{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}
```

### Export

Export per-visit verdict rows for a time range, for offline reconciliation and
settlement. Suitable for feeding into your billing pipeline.

```bash
GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_AD_APP_KEY
X-App-Secret: YOUR_AD_APP_SECRET
```

Each row carries the visit's `click_token` (when present), timestamp, and verdict
fields (`is_bot`, `score`, `level`, `action`), so you can join it back to your own
click logs.

## Click tokens {#click-tokens}

A **click token** ties a traffic provider's delivered click to the verdict the
visit ultimately receives. This is what lets advertisers and providers settle on
an independent, per-click human/bot conclusion.

The flow:

1. **Issue** — the traffic provider obtains a signed click token (one per click)
   when it routes a visitor toward the advertiser's landing page.
2. **Carry it on the destination URL** — append the issued token to the landing
   URL as a query parameter:

   ```
   https://advertiser.example/lp?click_token=ct_xxxxxxxx
   ```

3. **Read it on the page** — the [Web SDK](./web-sdk) reads the token from the URL
   automatically. If you use a different parameter name, set `tokenParam`:

   ```js
   BotSignal.init({ appKey: 'YOUR_AD_APP_KEY', tokenParam: 'click_token' });
   ```

4. **Reconcile** — look the click up later via `GET /v1/bot/verdict?click_token=…`
   or in the `export`, and join it back to the provider's delivery report.

::: info
The token is already signed when it is issued to you — you only need to **carry it
through to the landing URL**. There is nothing to sign or compute on your side.
:::

## Next steps

- [Verdict Reference](./verdict-reference) — the fields returned by these endpoints
- [Web SDK](./web-sdk) — collect verdicts on the landing page