Developer Reference

Funngrow Developer & Partner Documentation

Integrate with the Funngrow reward platform API. Build automated campaign submission pipelines, ingest verified task conversions, receive real-time S2S attribution postbacks, and manage escrow disbursements.

Production Base URLhttps://api.funngrow.com/api/v1

Sandbox / Staging URLhttps://staging-api.funngrow.com/api/v1

Payload ProtocolJSON (UTF-8), Content-Type: application/json

Authentication & Tokens

All non-public endpoints require a valid JSON Web Token (JWT) passed in the HTTP Authorization header as a Bearer token.

http

Authorization: Bearer <your_access_token>
Content-Type: application/json

Obtaining an Access Token

Submit user credentials to POST /api/v1/auth/login.

bash

curl -X POST https://api.funngrow.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "YourStrongPassword123"
  }'

API Overview & Response Envelope

All API responses follow a strict envelope schema with a boolean success flag, payload data, and request metadata containing distributed trace IDs and timestamps.

json

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "c1f7b8e2-9b24-4f81-a67b-...",
    "timestamp": "2026-10-01T22:30:00.000Z"
  }
}

Offers Catalog & Click Tracking

Explore active catalog offers and generate authenticated click sessions with cryptographic sub-IDs.

GET /api/v1/offersList eligible active offers

GET /api/v1/offers/categoriesList offer taxonomy categories

POST /api/v1/offers/:id/clickInitiate tracked click session

bash

curl -X POST https://api.funngrow.com/api/v1/offers/01923456-789a-bcde-f012-3456789abcde/click \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceType": "ANDROID",
    "referrerUrl": "https://funngrow.com/app"
  }'

Advertiser Campaigns

Deploy custom direct acquisition campaigns with specific task criteria: App Installs, Signups, Surveys, or Content Engagements.

POST /api/v1/advertiser/campaignsCreate new direct campaign

GET /api/v1/advertiser/campaignsList advertiser campaigns

PATCH /api/v1/advertiser/campaigns/:idPause, resume, or update campaign

json

{
  "advertiserId": "01923456-789a-bcde-f012-...",
  "categoryId": "00000000-0000-0000-0000-000000000001",
  "title": "Install & Review App",
  "shortDescription": "Download from Google Play and open.",
  "description": "Full terms and conditions...",
  "instructions": "1. Download\n2. Register\n3. Submit screenshot",
  "rewardAmount": 50.00,
  "totalBudgetAmount": 5000.00,
  "maxParticipants": 100,
  "targetCountries": ["IN"],
  "tasks": [
    {
      "title": "App Install Verification",
      "instructions": "Install the app and open once.",
      "taskType": "APP_INSTALL",
      "requirements": ["VERIFIED_COMPLETION"]
    }
  ]
}

Postbacks & S2S Webhooks

External offer providers notify Funngrow of conversions via server-to-server (S2S) postbacks.

http

GET https://api.funngrow.com/api/v1/postbacks/{sourceId}?click_id={clickSubId}&payout={payoutAmount}&tx_id={providerTxId}&sig={hmacSignature}

HMAC Signature Verification:

Signatures are computed via SHA-256 HMAC using your assigned source signing key: HMAC-SHA256(clickSubId + ":" + payoutAmount, secretKey).

Rewards & Disbursements

Earned rewards enter a PENDING state during fraud verification and clear to AVAILABLE balance upon approval.

GET /api/v1/analytics/me/earningsUser earnings breakdown

POST /api/v1/withdrawalsRequest payout withdrawal

Leaderboard & Analytics

Public and authenticated community leaderboard metrics across daily, weekly, and monthly intervals.

http

GET https://api.funngrow.com/api/v1/analytics/leaderboard?period=weekly

Error Responses & Formats

The API uses standard HTTP status codes along with descriptive JSON error structures.

400 Bad Request

Validation failure or missing required body parameters.

401 Unauthorized

Bearer token missing, invalid signature, or expired session.

403 Forbidden

Insufficient permissions or account status restriction.

429 Too Many Requests

Rate limit exceeded. Check Retry-After response header.

Rate Limiting & Headers

API requests are guarded with in-memory / Redis throttlers. Responses include tracking headers:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1727823600