Integrate Campaigns

This guide explains how to create and manage Campaigns, authenticate using Campaign API Keys, and trigger lifecycle and payout events. It also covers how to test the flow end-to-end.

Prerequisites

• An Oncade developer account and access to your business.
• DevPortal → Campaigns to create/manage campaigns.
• A funded Campaign

Authorization: Bearer <campaign_api_key>
X-Oncade-API-Version: v1
X-Campaign-Id: <campaignId>

Create and configure a campaign

1. Open Dashboard → Campaigns and click Create Campaign.
2. Enter a name, pick an environment (test or live), and add at least one event with code, name, and payoutAmount.
3. After creation, fund the campaign with the payout token, then use Start when ready.

Core endpoints

Use these endpoints from your server or trusted backend. Examples use environment variables $CID and $CAMPAIGN_KEY.

Get details

curl -s \
  -H "Authorization: Bearer $CAMPAIGN_KEY" \
  -H "X-Oncade-API-Version: v1" \
  -H "X-Campaign-Id: $CID" \
  https://<host>/api/v1/campaign/$CID

Start and Stop

curl -s -X PUT \
  -H "Authorization: Bearer $CAMPAIGN_KEY" \
  -H "X-Oncade-API-Version: v1" \
  -H "X-Campaign-Id: $CID" \
  -H "Idempotency-Key: start-$(uuidgen)" \
  https://<host>/api/v1/campaign/$CID/start

Withdraw remaining funds

curl -s -X POST \
  -H "Authorization: Bearer $CAMPAIGN_KEY" \
  -H "X-Oncade-API-Version: v1" \
  -H "X-Campaign-Id: $CID" \
  -H "Idempotency-Key: withdraw-$(uuidgen)" \
  https://<host>/api/v1/campaign/$CID/withdraw

Record an event payout

curl -s -X POST \
  -H "Authorization: Bearer $CAMPAIGN_KEY" \
  -H "X-Oncade-API-Version: v1" \
  -H "X-Campaign-Id: $CID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: event-$(uuidgen)" \
  -d '{"eventCode":"EARN5","userRef":"usr_abc123"}' \
  https://<host>/api/v1/campaign/$CID/events

Lifecycle controls

• Start and Stop return 202 Accepted and enqueue background jobs.
• Use GET /api/v1/campaign/$CID to verify status transitions before changing traffic.
• Use Withdraw after a campaign is stopped to recover remaining funds.

Link users to your campaign

Campaigns pay out to users that have been linked/approved for the campaign. Poll the link session to retrieve theuserRef to use in event submissions.

curl -s 'https://<host>/api/v1/users/link/details?session=<sessionKey>'

Test the flow end-to-end

1. From Campaigns, create a test campaign in the test environment and fund it.
2. Start the campaign, then call GET /api/v1/campaign/$CID to confirm status and balances.
3. Submit an event with a known userRef. Unknown refs should return 404.
4. Stop the campaign and then request a withdrawal. While Active, withdrawals should return 400.

Growth and acquisition with link invites

Use campaign link invites for acquisition channels where users self-serve account linking. Each invite can be labeled for attribution and controlled with usage caps, expiration windows, or pause/revoke states.

• Create invite links for specific channels (email, creators, communities).
• Set maxUses and expiresAt for controlled rollouts.
• Pause or revoke invites when campaigns or channels change.

Rewards observability and operations

• Use campaign details to track status and available balances.
• List linked users to audit enrollment and linkage health.
• Inspect user event history for reconciliation and support workflows.
• List configured events to validate your reward catalog before launch.

Where to manage campaigns

• List: /dashboard/campaigns
• Create: /dashboard/campaigns/new
• Detail: /dashboard/campaigns/[campaignId]
• Webhook settings: /dashboard/campaigns/[campaignId]/webhook

References

• Campaigns API