Developer Reference v1

Developer Documentation & API Reference

Build bespoke rewards frontends, automate catalog synchronization, and handle conversion callbacks with our institutional REST API suite.

Operational tokens and signing secrets are provisioned inside the publisher dashboard upon account approval.

# Authentication # REST Endpoints # S2S Postbacks # HMAC Signatures # Error Handling

API Authentication

Bearer Token Authorization

Authenticate all publisher API requests using your secret API key in the Authorization HTTP header. API keys are generated in the publisher dashboard with granular permission scopes.

Authorization: Bearer cpaad_live_9f83b2a1c0d4e5f6...

Standard Rate Limit: 120 requests/minute per key. Reports Rate Limit: 30 requests/minute.

REST API v1 Endpoints

Versioned JSON Resource Contracts

GET/api/v1/offers

Query approved offers with country/device filters

GET/api/v1/offers/{offerId}

Fetch full offer requirements and creative copy

GET/api/v1/placements

List registered placements and tokens

POST/api/v1/placements

Create new placement with domain allowlist

GET/api/v1/balance

Retrieve ledger-derived available & pending balance

POST/api/v1/postback/test

Dispatch synthetic non-financial test postback

HMAC-SHA256 Postback Signature Verification

Cryptographic Webhook Authenticity

All postback webhooks include the X-CPAAD-Signature header. Verify the signature using your webhook secret to prevent unauthorized spoofing of conversion rewards.

// Node.js Webhook Signature Verification Example
import crypto from 'crypto';

function verifyCpaadSignature(payload, signatureHeader, secret) {
  const [tPart, v1Part] = signatureHeader.split(',');
  const timestamp = tPart.split('=')[1];
  const signature = v1Part.split('=')[1];

  const signedPayload = timestamp + '.' + payload;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Standard Error Responses

RFC 7807 Problem Details

API errors return standard machine-readable problem detail documents:

{
  "type": "https://api.cpaad.net/v1/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit of 120 requests per minute exceeded.",
  "code": "ERR_RATE_LIMIT",
  "timestamp": "2026-10-10T12:00:00Z"
}