# Card Campaigns & Deals (SBX-FIRSAT)

The current campaigns of Wings, World, Bonus, Maximum and Axess cards — installments, discounts, points and prize draws — tagged by sector and audience segment (student, traveller, car owner and more), refreshed daily.

Version: v1.0

## Authentication

Send your API key on every request, either as a Bearer token or as the `apikey` query parameter:

```
Authorization: Bearer <YOUR_API_KEY>
https://api.servicebox.io/v1/deals/...?apikey=<YOUR_API_KEY>
```

Get a key: sign up at https://servicebox.io/en/signup and create one on the dashboard. An agent can sign up itself with `POST https://api.servicebox.io/v1/accounts` and `{"email": "...", "apis": ["deals"]}`: the owner of the mailbox approves by email and the agent collects a short-lived key by polling the returned `poll_url`.

## Base URL

`https://api.servicebox.io`

## Endpoints

### GET /v1/deals/campaigns

**List card campaigns**

The current campaigns of Turkish credit-card programs — Wings, World, Bonus, Maximum and Axess — read daily from the programs' public campaign pages: installment offers, discounts, points (chip-para, Bonus, Worldpuan, MaxiPuan, miles) and prize draws, with the merchant, dates, amounts parsed from the headline, our sector tags and audience segments (student, traveler, driver, homemaker, …). Filter by `card`, `sector`, `segment`, `reward`, `brand`, a text search `q` (Turkish letters optional), and `ending_within` days; `status=ended` lists what ended in the last week. Soonest to end first. Use when the user asks what campaigns, discounts, installment offers or points their card has, for a shop or brand, for a kind of spending (market, fuel, travel, clothing), or for a kind of person; link the `url` for the terms — the program's page is authoritative.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `card` | query | string | no | Comma-separated card program ids from /deals/cards, e.g. bonus,axess. |
| `sector` | query | string | no | Comma-separated sector ids from /deals/sectors (any of), e.g. grocery,dining. |
| `segment` | query | string | no | Comma-separated segment ids from /deals/segments (any of), e.g. student,traveler. |
| `reward` | query | string | no | Comma-separated reward types (any of): installment, discount, points, draw, other. |
| `brand` | query | string | no | A merchant name as it appears in `brand`, e.g. Trendyol (case-insensitive). |
| `q` | query | string | no | Words to find at the start of words of the title, brand or summary; Turkish letters optional: `market`, `akaryakit`, `trendyol`. |
| `status` | query | string (`active`, `ended`, `all`) | no | `active` (default), `ended` (ended within the last 7 days) or `all`. |
| `ending_within` | query | integer | no | Only active campaigns ending within this many days (1–60), soonest first. |
| `limit` | query | integer | no | Items per page, 1–200. |
| `cursor` | query | string | no | The `next_cursor` of the previous page, with the same filters. |

**Example**

```bash
curl "https://api.servicebox.io/v1/deals/campaigns" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/campaigns/{id}

**Get a campaign**

One campaign by its id from /deals/campaigns, e.g. bonus:bauhaus-yapi-taksit-kampanyasi. Ended campaigns stay for 7 days, then 404.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A campaign id, `<card>:<slug>`. |

**Example**

```bash
curl "https://api.servicebox.io/v1/deals/campaigns/<id>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/cards

**List card programs**

The five card programs covered — Wings (Şekerbank), World (Yapı Kredi), Bonus (Garanti BBVA), Maximum (İşbank), Axess (Akbank) — with their active campaign count, when each program's page was last read completely (`lastUpdated`), and the attribution to show. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/deals/cards" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/sectors

**List sectors**

What a campaign is for — grocery, fuel & automotive, fashion, electronics, home, travel, dining, education, health, entertainment, online shopping, insurance, bills & taxes, card services, other — in English and Turkish, with active counts. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/deals/sectors" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/segments

**List audience segments**

Who a campaign is for — students, parents, travellers, people spending abroad, car owners, home makers, fashion and tech shoppers, online shoppers, diners, grocery shoppers, culture, health & sport, pet owners, football fans, bill payers, mobile/QR payers, new card applicants — in English and Turkish, with active counts. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/deals/segments" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Errors

Errors are RFC 9457 `application/problem+json` bodies with a machine-readable `type`.

- `401` — the key is missing, unknown, expired or revoked.
- `402` — not enough credits: the body carries `credits_required` and `upgrade_url` (https://servicebox.io/en/pricing).
- `403` — the key is not allowed to call this API.
- `429` — rate limited: wait `retry_after` seconds (also sent as the `Retry-After` header); `upgrade_url` points to a larger plan.

## Links

- OpenAPI document: https://api.servicebox.io/v1/deals/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-FIRSAT
- API page: https://servicebox.io/en/apis/deals