Aktvator
Developer Documentation

Build on Aktvator

Embed Aktvator's performance network directly into your product. Run verified campaigns, track attribution, receive real-time events, and trigger reward payouts — all through a clean REST API.

Get your API keyTalk to us

Base URL

Production
https://api.aktvator.com

All endpoints are relative to this base. Use HTTPS only — HTTP requests are rejected.

Capabilities

Everything in the API

API Key auth

Generate scoped API keys from your organization dashboard. Every request authenticates with a bearer token — no OAuth dance required.

REST API

Full CRUD over campaigns, gigs, members, and wallets. Paginated lists, filter params, and predictable JSON responses throughout.

Attribution

Generate unique tracking links and shortcodes. Attach them to Aktvators so every conversion, referral, or activation is traceable back to the individual.

Event ingestion

Push custom conversion events from your backend. Aktvator matches them against active campaigns and queues reward evaluation automatically.

Webhooks

Subscribe to real-time events — campaign status changes, action verifications, reward payouts. Retry logic and delivery logs are built in.

Campaign reward rules

Programmatically configure reward tiers, eligibility criteria, and caps. Change rules at any time without interrupting live campaigns.

Authentication

API key bearer token

Every API request must include your organization API key as a bearer token in the Authorization header.

  • →Keys are created per organization — go to Settings → API Keys in your seller dashboard.
  • →The full token is shown only once at creation time. Store it in your secrets manager.
  • →Keys can be given an expiry date and revoked at any time from the dashboard.
  • →Requests without a valid key return 401 Unauthorized.
Request header
Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx
Example — list campaigns
curl https://api.aktvator.com/campaigns \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

REST API

Core endpoints

All responses are JSON. Errors return a consistent shape with message and statusCode.

Campaigns

GET/campaignsList all campaigns for your organization.
POST/campaignsCreate a new campaign.
GET/campaigns/:idFetch a single campaign.
GET/campaigns/:id/performanceCampaign performance metrics.
POST/campaigns/:id/status/:statusUpdate campaign status (draft → active → paused → ended).

Gigs

GET/gigsList gigs across your campaigns.
POST/gigsCreate a gig inside an existing campaign.
POST/gigs/:id/status/:statusPublish, pause, or close a gig.

Organization

GET/organizations/:idFetch organization details.
PATCH/organizations/:idUpdate name, description, website.
GET/organizations/:id/walletCurrent wallet and available balance.
POST/organizations/:id/wallet/topupInitiate a wallet top-up (returns payment URL).
GET/organizations/:id/membersList team members and roles.
POST/organizations/:id/membersInvite a new team member.
GET/organizations/:id/api-keysList API keys (tokens are not exposed after creation).

Attribution

Tracking links & codes

Every Aktvator gets a unique attribution link or shortcode. When a customer converts through their link, Aktvator records the referral and queues reward evaluation.

  • →Links — full redirect URLs that record a click before sending the customer to your page.
  • →Codes — short alphanumeric codes your customers enter at checkout or sign-up.
  • →Pass the code in your event ingestion payload to tie the conversion back to the Aktvator.
Create an attribution link
POST /attribution/links
Content-Type: application/json

{
  "campaignId": "camp_xxxxxxxx",
  "targetUrl": "https://yoursite.com/signup",
  "aktvatorId": "aktv_xxxxxxxx"
}
Response
{
  "id": "link_xxxxxxxx",
  "shortUrl": "https://go.aktvator.com/abc123",
  "targetUrl": "https://yoursite.com/signup",
  "code": "ABC123"
}

Event Ingestion

Push conversion events

When a conversion happens in your system — a sign-up, a purchase, a product activation — send the event to Aktvator. We match it against active reward rules and automatically evaluate payouts.

  • →Include the attributionCode or attributionLinkId to identify the Aktvator.
  • →eventType must match the action type defined in your campaign gig.
  • →Include a unique idempotencyKey to prevent duplicate reward evaluation.
POST /events/ingest
{
  "eventType": "customer.signup",
  "campaignId": "camp_xxxxxxxx",
  "attributionCode": "ABC123",
  "idempotencyKey": "order_9988776655",
  "metadata": {
    "customerId": "cust_12345",
    "email": "customer@example.com",
    "plan": "pro"
  }
}
Response
{
  "received": true,
  "eventId": "evt_xxxxxxxxxxxxxxxx",
  "status": "queued"
}

Webhooks

Real-time event delivery

Register HTTPS endpoints to receive events as they happen. Aktvator retries failed deliveries with exponential back-off. Every attempt is logged — view them from the dashboard or API.

Register an endpoint

POST /organizations/:id/webhook-endpoints
{
  "name": "Production webhook",
  "targetUrl": "https://yoursite.com/webhooks/aktvator",
  "subscribedEvents": [
    "action_attempt.verified",
    "reward.paid",
    "campaign.approved"
  ]
}

Incoming payload shape

POST your-endpoint
{
  "id": "evt_xxxxxxxxxxxxxxxx",
  "type": "action_attempt.verified",
  "organizationId": "org_xxxxxxxx",
  "createdAt": "2025-10-14T12:00:00.000Z",
  "data": {
    "actionAttemptId": "att_xxxxxxxx",
    "aktvatorId": "aktv_xxxxxxxx",
    "campaignId": "camp_xxxxxxxx",
    "rewardAmount": 2500
  }
}

Available event types

campaign.createdA new campaign was created in your organization.
campaign.approvedPlatform approved a campaign for the marketplace.
action_attempt.submittedAn Aktvator submitted a new proof of work.
action_attempt.verifiedA submission passed verification.
action_attempt.rejectedA submission failed verification.
reward.paidA reward was paid out to an Aktvator.
member.invitedA user was invited to join your organization.
wallet.creditedYour organization wallet was topped up.

Quickstart

From zero to first event in 5 steps

01

Create an organization

Sign up on the seller dashboard and complete your profile. Your organization ID is the root identifier for all API calls.

02

Generate an API key

Go to Settings → API Keys, create a named key, and copy the token. It is shown once — store it securely.

03

Call the API

Include the key as a bearer token in every request header. The base URL is your environment's API root.

04

Register a webhook

POST your endpoint URL to /organizations/:id/webhook-endpoints and select the events you need.

05

Ingest events

From your backend, POST to /events/ingest with a standardised event body. Aktvator evaluates each event against live reward rules.

Rate limits

All endpoints are rate-limited per API key. Responses include standard rate limit headers. Exceeding the limit returns 429 Too Many Requests.

Errors

Every error returns a JSON body with statusCode, message, and optionally errors for validation failures.

Versioning

The current API is v1. Breaking changes will be versioned. You will receive advance notice via email and webhook before any breaking change deploys.

Ready to integrate?

Create an organization, generate an API key, and start sending events. Reach out if you need a custom integration or want to walk through the API with our team.

Create an organizationContact us