Invitebase | Campaigns

A Campaign is a referral campaign: it holds the qualification gate that defines what counts as a referral, and the reward configuration that defines how people get paid.

The Campaign object

Field	Type	Description
`id`	string	Unique identifier (a UUID).
`object`	string	Always `campaign`.
`name`	string	Display name, e.g. `Refer a friend — give a month, get a month`.
`status`	string	`active` or `paused` (or `archived` after archiving).
`reward`	array	One or more reward configurations, one per recipient. A single-sided campaign has one entry (the referrer); a double-sided campaign adds a second entry for the referred user.
`mode`	string	`test` or `live`.
`livemode`	boolean	Whether the campaign exists in live mode.
`created_at`	string (date-time)	Creation time.

The qualification gate — what counts as a referral — is built in the Campaign Builder, not through the API. There's no gate JSON to send or receive: the API doesn't accept a gate definition on create or update, and campaign responses don't include one. To see how a referral is progressing against its gate, read gate_progress on the referral. See Qualification gates for how gates work.

The RewardConfiguration object

Field	Type	Description
`method`	string	`in_app`, `free_access`, `monetary`, `gift_card`, `paypal`, `venmo`, or `ach`. What the recipient gets — never how it reaches them, which is `delivery`. `in_app` and `free_access` are app grants with no money movement. The rest are monetary payouts drawn from your prefunded balance: `monetary` lets the recipient pick the exact card or cash destination at claim time, while `gift_card`, `paypal`, `venmo`, and `ach` pin that one rail up front.
`recipient`	string	`referrer` or `referred_user`. Add one reward configuration per side to make a campaign double-sided.
`amount`	integer	Value in the smallest currency unit (money methods) or app-defined units.
`currency`	string	ISO 4217 code, lowercase, e.g. `usd`.
`free_access_duration`	object	Required for `method: free_access`, rejected for every other method. `{ "count": 3, "unit": "month" }` — `count` is 1–120, `unit` is `day`, `week`, or `month`. This is the term your referral pages advertise. For code deliveries it is advertised only: the enforced term is baked into the code you supply, so generate codes that match.
`delivery`	string	For `method: free_access` — how the grant reaches the recipient. `webhook` (default) calls your backend over the signed reward webhook. `manual`, `api`, and `app_store_connect` hand over a code from campaign inventory; an active campaign using one of them requires stocked inventory. `revenuecat` grants the entitlement through your RevenueCat project.
`in_app_payload`	object	For `method: in_app` — what to grant (e.g. `{ "grant": "gold_skin" }`).
`milestone_threshold`	integer	Reward only after the referrer reaches N validated referrals (e.g. 5).
`cap_per_referrer`	integer	Max rewards per referrer (fraud control).
`cap_per_month`	integer	Max rewards per campaign per month (fraud control).
`expires_in_days`	integer	Reward expires if unfulfilled after this many days.

List campaigns

GET/v1/campaigns

Returns a paginated list of campaigns.

Parameter	In	Type	Required	Description
`limit`	query	integer	No	1–100, default 25.
`starting_after`	query	string	No	Cursor (campaign id) for the next page.

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

Response — 200 OK:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
      "object": "campaign",
      "name": "Refer a friend — give a month, get a month",
      "status": "active",
      "reward": [
        {
          "method": "free_access",
          "recipient": "referrer",
          "free_access_duration": { "count": 1, "unit": "month" }
        },
        {
          "method": "free_access",
          "recipient": "referred_user",
          "free_access_duration": { "count": 1, "unit": "month" }
        }
      ],
      "mode": "test",
      "livemode": false,
      "created_at": "2026-07-01T09:15:00Z"
    }
  ]
}

Create a campaign

POST/v1/campaigns

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string	No	Retries with the same key return the original result.
`name`	body	string	Yes	Display name.
`status`	body	string	No	`active` or `paused`. Defaults to `active`.
`reward`	body	array	Yes	One or more RewardConfiguration objects, one per recipient (`referrer` and/or `referred_user`).

The API creates the campaign and its rewards; build its qualification gate in the Campaign Builder. Until a gate is configured, the campaign can't validate referrals.

curl https://api.invitebase.com/v1/campaigns \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refer a friend — give a month, get a month",
    "reward": [
      {
        "method": "free_access",
        "recipient": "referrer",
        "free_access_duration": { "count": 1, "unit": "month" }
      },
      {
        "method": "free_access",
        "recipient": "referred_user",
        "free_access_duration": { "count": 1, "unit": "month" }
      }
    ]
  }'

Response — 201 Created: the Campaign object.

{
  "id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
  "object": "campaign",
  "name": "Refer a friend — give a month, get a month",
  "status": "active",
  "reward": [
    {
      "method": "free_access",
      "recipient": "referrer",
      "free_access_duration": { "count": 1, "unit": "month" }
    },
    {
      "method": "free_access",
      "recipient": "referred_user",
      "free_access_duration": { "count": 1, "unit": "month" }
    }
  ],
  "mode": "test",
  "livemode": false,
  "created_at": "2026-07-09T10:00:00Z"
}

Retrieve a campaign

GET/v1/campaigns/{campaignId}

Parameter	In	Type	Required	Description
`campaignId`	path	string	Yes	The campaign id.

curl https://api.invitebase.com/v1/campaigns/7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15 \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

Response — 200 OK: the Campaign object. Returns 404 if the campaign does not exist.

Update a campaign

PATCH/v1/campaigns/{campaignId}

All body fields are optional; only supplied fields change.

Parameter	In	Type	Required	Description
`campaignId`	path	string	Yes	The campaign id.
`name`	body	string	No	New display name.
`status`	body	string	No	`active`, `paused`, or `archived`.
`reward`	body	array	No	Replacement array of RewardConfiguration objects (replaces all sides).

curl -X PATCH https://api.invitebase.com/v1/campaigns/7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15 \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response — 200 OK: the updated Campaign object.

{
  "id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
  "object": "campaign",
  "name": "Refer a friend — give a month, get a month",
  "status": "paused",
  "reward": [
    {
      "method": "free_access",
      "recipient": "referrer",
      "free_access_duration": { "count": 1, "unit": "month" }
    },
    {
      "method": "free_access",
      "recipient": "referred_user",
      "free_access_duration": { "count": 1, "unit": "month" }
    }
  ],
  "mode": "test",
  "livemode": false,
  "created_at": "2026-07-09T10:00:00Z"
}

Archive a campaign

DELETE/v1/campaigns/{campaignId}

Archiving stops new referrals; existing referrals continue through their lifecycle.

Parameter	In	Type	Required	Description
`campaignId`	path	string	Yes	The campaign id.

curl -X DELETE https://api.invitebase.com/v1/campaigns/7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15 \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

Response — 204 No Content. Returns 404 if the campaign does not exist.

What's next

Referrers

The end-users of your app who refer others.

Referral links

Create unique, attributable share links and codes.

Referrals

Individual referral attempts and their lifecycle state.

Rewards

What's owed once a referral validates, and its fulfillment.

Campaigns

On this page