API Docs — BonusWave

BonusWave has a read-only public API for Premium users. Generate a long-lived key in Settings, then fetch your bonuses programmatically — build briefings, integrations, or automations on top of your pipeline.

Authentication

All requests must include your API key in the Authorization header, prefixed with Bearer:

Authorization: Bearer bw_YOUR_KEY_HERE

Keys are long-lived and tied to your account. You can have one active key at a time. If a key is compromised, revoke it from Settings and generate a new one. Keys stop working immediately if your Premium subscription lapses.

Endpoint

GET /api/v1/bonuses

Returns all of your bonuses, newest first. There is no pagination — typical users have under a hundred bonuses, so the full list is returned in a single response.

Example request

curl https://www.bonuswave.app/api/v1/bonuses \
  -H 'Authorization: Bearer bw_YOUR_KEY_HERE'

Example response

{
  "data": [
    {
      "id": "9f2c8a1e-...",
      "bank": "Example Bank",
      "accountType": "Checking",
      "bonusAmount": 300,
      "stage": "Open",
      "dateOpened": "2026-05-01",
      "bonusDeadline": "2026-08-01",
      "bonusReceived": false,
      "ddCountRequired": 2,
      "ddTotalRequired": 5000,
      "ddCountCompleted": 1,
      "ddTotalCompleted": 2500,
      "ddPaycheckFunded": true,
      "safeToCloseDate": "2026-08-01"
      // ...all other Bonus fields
    }
  ]
}

JavaScript example

const res = await fetch('https://www.bonuswave.app/api/v1/bonuses', {
  headers: { Authorization: 'Bearer ' + process.env.BONUSWAVE_API_KEY },
});
const { data } = await res.json();
console.log(data);

Bonus fields

Each bonus has the following fields:

Identity

idstring: Unique identifier for the bonus.
bankstring: Bank or credit union name.
accountTypestring: Account type, e.g. "Checking", "Savings".
bonusAmountnumber: Bonus amount in whole dollars.
isBusinessboolean: Whether this is a business account.
playerstring: Player label (for multiplayer accounts). Empty string if not set.

Stage and status

stagestring: One of: "Prospecting", "Open", "Waiting for Bonus", "Bonus Received", "Closed".
bonusReceivedboolean: Whether the bonus has been received.
taxReportedboolean: Whether the bonus has been reported for taxes.

Dates

dateOpenedstring | null: Date the account was opened (YYYY-MM-DD).
requirementsDeadlinestring | null: Date by which the bonus requirements (DDs, card transactions, min balance) must be met (YYYY-MM-DD).
bonusDeadlinestring | null: Date by which the bonus should post — the expected payout deadline (YYYY-MM-DD).
bonusDatestring | null: Date the bonus actually posted (YYYY-MM-DD).
churnableDatestring | null: Date the bank becomes churnable again (YYYY-MM-DD).
safeToCloseDatestring | null: Earliest date the account can be closed without losing the bonus to an early closure fee or clawback (YYYY-MM-DD). Drives the digest's 'safe to close' nudge.
dateClosedstring | null: Date the account was closed (YYYY-MM-DD).

Direct deposit requirements

ddCountRequirednumber: Number of direct deposits required.
ddMinPerDepositnumber: Minimum amount per individual direct deposit, in dollars.
ddTotalRequirednumber: Total direct deposit amount required, in dollars.
ddCountCompletednumber: Direct deposits completed so far.
ddTotalCompletednumber: Total direct deposit amount completed so far, in dollars.
ddPaycheckFundedboolean: Whether DD requirements are funded from the user's paycheck (true, default) or from an external source such as an ACH push or brokerage transfer (false). Used by the dashboard to size the paycheck allocation bar.

Other requirements

cardTxnRequirednumber: Number of debit card transactions required.
cardTxnCompletednumber: Debit card transactions completed so far.
minBalancenumber: Minimum balance to maintain, in dollars.
minBalanceDaysnumber: Number of days to maintain the minimum balance.
minBalanceMetboolean: Whether the minimum balance requirement has been met.

Notes

requirementsstring: Free-text summary of bonus requirements.
notesstring: Free-text notes.
feeNotesstring: Free-text notes about fee waivers.

Errors

Errors are returned as JSON with an error field containing a machine-readable code:

Status	Error code	Meaning
401	`invalid_api_key`	Missing, malformed, or revoked key.
403	`premium_required`	The key is valid but the account is not on an active Premium plan.
500	`internal_error`	Something went wrong on our end. Try again, or email hello@bonuswave.app if it persists.

Versioning

This is v1. Breaking changes will go into /api/v2/; we won't break /api/v1/ under you. New fields may be added to existing endpoints — your code should ignore unknown fields rather than fail on them.

Questions

Hit a wall, want a new endpoint, or building something cool? Email hello@bonuswave.app.