Developer Knowledgebase

API keys are generated per member account from the dashboard at /api-keys or via POST /api/v1/members/api-key.

Keys use the format ref_ followed by 48 hex characters (e.g. ref_a1b2c3...).

Include your key in the X-API-Key header on every authenticated request.

You can also exchange email + password for a JWT token via POST /api/v1/auth/token. Tokens expire after 30 days.

Each API key has access to all brands and campaigns owned by that member account.

A brand represents a domain/website you want to run referral campaigns for.

Create a brand with POST /api/v1/brands — just pass your website URL and we auto-extract the domain.

Each brand has its own campaigns, participants, and stats.

You can manage multiple brands under one account — perfect for agencies or multi-site businesses.

Brand stats are available at GET /api/v1/brands/:brandId/stats (total campaigns, participants, shares, clicks, impressions).

Campaigns are referral programs tied to a specific brand.

Set goal_type to "signup" or "visit" to define how rewards are triggered.

num_signups controls how many referrals a participant needs before earning a reward.

Campaigns can be "public" (requires paid plan) or "private".

Each campaign can have its own widget, lander page, reward configuration, and contest.

Type 1 — Coupon: Upload coupon codes to the campaign. When a referral goal is met, the next available coupon is assigned and marked as used.

Type 3 — Custom Message: A free-form message displayed to the participant when their goal is met.

Type 5 — Cash: A dollar value recorded against the participant's reward record.

Type 4 — Crypto Token (legacy): Token transfer via blockchain. Only available for VNOC-linked domains.

Two-way rewards: Enable reward_invited on the campaign to also reward the newly referred user.

Register webhook URLs at POST /api/v1/webhooks — we POST a JSON payload when a participant signs up.

Payload includes event type, participant details, campaign ID, and signup timestamp.

For Zapier: use POST /api/v1/zapier/auth to validate your key, and GET /api/v1/zapier/contacts as the polling trigger.

You can scope webhooks to a specific campaign_id, or leave it null for account-wide notifications.

Basic signup: POST /api/v1/signups — creates a participant record and fires any configured webhook.

Referral signup: POST /api/v1/signups/referral — pass a base64-encoded referral code to track who referred whom and automatically process rewards.

The referral code encodes "campaign_id:social_type:participant_id[:invited_id]".

If a participant was already invited by someone else, the API returns a message instead of overwriting the referral chain.

Widget-based signups at POST /api/widget/signup handle the same flow for embedded widgets.

Each campaign can have a landing page configuration (campaign_lander) with custom header, footer, background, and fonts.

Retrieve it via GET /api/v1/lander?campaign_id=123 — returns lander settings plus brand info and social URLs.

If no custom lander exists, a default template is returned with the brand's background image.

Lander templates are managed in the dashboard editor.

All responses return { "success": true/false, "data": ... } or { "success": false, "error": "..." }.

List endpoints support ?page=1&limit=20 (max 100 per page).

Pagination metadata is included: { page, limit, total, totalPages }.

HTTP status codes: 200 (success), 201 (created), 400 (bad request), 401 (unauthorized), 404 (not found), 409 (conflict), 500 (server error).