API overview

The Invitebase API is a REST API over JSON — the dashboard and the SDKs are clients of it. Every resource in the referral lifecycle (campaigns, referrers, links, referrals, rewards) is readable and writable through it.

Base URL and versioning

All requests go to:

https://api.invitebase.com

Every path is versioned under /v1. Breaking changes ship as a new version prefix; /v1 stays stable.

Authentication

There are two key types. Both are scoped to your organization and to a mode (test or live).

Secret keys have full access. Publishable keys are limited to the SDK-safe operations:

• Ingest an event — POST /v1/events
• Create or identify a referrer — POST /v1/referrers
• Create a referral link — POST /v1/referral-links

Every other endpoint requires a secret key. Keys are named, shown once at creation, and can be rolled or revoked from Developer tools in the dashboard.

curl https://api.invitebase.com/v1/campaigns \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

Test and live mode

The key determines the mode — there is no separate sandbox host. sk_test_… and pk_test_… operate on test data; sk_live_… and pk_live_… on live data. Test-mode data is fully isolated, never billed, and never moves real money. Every API object carries a mode field (test or live) and a livemode boolean so you can always tell which side you are looking at.

Idempotency

All POST requests accept an Idempotency-Key header. Retries with the same key return the original result, so event ingestion, link creation, and top-ups are safe to retry after a timeout or network failure.

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Idempotency-Key: 4f9c1b2e-7a31-4c2d-9d1a-6b8e2f0c5a77" \
  -H "Content-Type: application/json" \
  -d '{"name": "signup", "referred_user_id": "usr_123"}'

Pagination

List endpoints share one cursor-based convention:

Responses are wrapped in a list envelope:

{
  "object": "list",
  "data": [{ "...": "..." }],
  "has_more": true
}

When has_more is true, pass the last object's id as starting_after to fetch the next page.

Errors

Errors return a conventional HTTP status code and a JSON envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "referred_user_id is required.",
    "param": "referred_user_id"
  }
}

See Errors for the full code list and retry guidance.

Resources