TumaMaoni API Documentation

# Introduction

TumaMaoni is a customer feedback platform for Tanzanian and global businesses. Our developer API lets you collect, read and analyse feedback programmatically — using prepaid tokens instead of a subscription.

What the API gives you

• Collect feedback — submit ratings and comments from your app or widget in a single request.
• Read feedback — list and search everything customers have shared, with pagination and filters.
• Analytics — overviews, trends, department and product breakdowns, satisfaction scores.
• Simple billing — 1 token = 1 request = TZS 1. No monthly fees, no credit checks.
• Ready widget — a drop-in JavaScript feedback bubble for websites, powered by publishable keys.

Base URL

Pricing

Next steps

1. Create your account and open the Developer API portal.
2. Generate an API key — you get 100 free tokens.
3. Make your first request (see Quickstart).

# Quickstart

Get your first feedback submitted through the API in about two minutes.

1. Create an API key

1. Log in to TumaMaoni and open the Developer API portal.
2. Open the API keys tab and click Create an API key.
3. Choose Secret for server-side access (full access) or Publishable for the client-side widget.
4. Copy the key immediately — it is only shown once.

Creating your first key also grants you 100 free tokens.

2. Check your balance

curl https://tumamaoni.com/api/v2/balance \
  -H "Authorization: Bearer TM-secret-your_key_here"

{
  "success": true,
  "message": "Success",
  "data": {
    "user_id": 42,
    "balance": 100,
    "total_purchased": 0,
    "total_spent": 0,
    "free_granted": 1,
    "used_today": 0,
    "rejected_insufficient": 0,
    "min_topup": 1000,
    "max_topup": 200000,
    "tokens_per_request": 1,
    "topup_url": "https://tumamaoni.com/api"
  }
}

3. Submit your first feedback

This paid request costs 1 token and submits feedback to your own business.

curl -X POST https://tumamaoni.com/api/v2/feedbacks/submit \
  -H "Authorization: Bearer TM-secret-your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "John Doe",
    "email_phone": "john@example.com",
    "comments": "Great service, very fast!",
    "satisfaction_score": 5,
    "recommend": "yes",
    "department": "Support",
    "product_service": "Mobile App"
  }'

{
  "success": true,
  "message": "Feedback submitted successfully",
  "data": { "feedback_id": 1024 }
}

# Authentication

Authenticate every request with your API key. Send it as a Bearer token or in the X-API-Key header.

Bearer token

Authorization: Bearer TM-secret-your_key_here

X-API-Key header

X-API-Key: TM-secret-your_key_here

Key formats

Authenticating requests

Most endpoints require authentication and return 401 with an invalid or missing key. The POST /feedbacks/submit endpoint also accepts publishable keys so your widget can submit feedback directly.

# API keys

Create and manage keys from the Developer API portal or through the API itself. Keys are hashed in our database — the raw key is shown only once at creation.

Secret vs publishable

Allowed domains (publishable keys)

You can restrict a publishable key to specific domains. Requests are checked against the Referer header, so the widget will only run on your sites. One domain per line, e.g. myapp.com and localhost. Leave empty to allow any domain.

Create a key via the API

Zero-token endpoint. Requires an existing secret key.

curl -X POST https://tumamaoni.com/api/v2/keys \
  -H "Authorization: Bearer TM-secret-your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Mobile App",
    "key_type": "publishable",
    "allowed_referrers": ["myapp.com", "localhost"]
  }'

The response returns your new key once:

{
  "success": true,
  "message": "API key created. Store it now — you will not see it again.",
  "data": {
    "id": 7,
    "key": "TM-pub-a1b2c3d4e5...",
    "key_type": "publishable",
    "name": "My Mobile App"
  }
}

# Token billing

TumaMaoni API uses simple prepaid billing. There are no subscriptions — you buy tokens and each paid request spends exactly one.

How it works

1. 1 token = 1 request — every paid endpoint costs exactly 1 token (TZS 1).
2. Free grant — creating your first API key credits 100 free tokens.
3. Top up via mobile money — buy tokens with M-Pesa, Airtel or Tigo through CamelPay.
4. Instant credit — once payment is confirmed, your balance updates automatically.
5. Refunds — if a paid request fails (4xx/5xx), the token is refunded automatically.

Prices

Top up from your server

Zero-token endpoint. Initiates a CamelPay mobile money charge — the customer gets a USSD prompt on their phone.

curl -X POST https://tumamaoni.com/api/v2/topup \
  -H "Authorization: Bearer TM-secret-your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "amount_tsh": 5000, "phone": "0712345678" }'

{
  "success": true,
  "message": "Payment initiated. Please check your phone for the USSD prompt.",
  "data": {
    "order_ref": "TT-42-1722...",
    "reference": "cp_a1b2c3d4...",
    "tokens": 5000,
    "tsh_amount": 5000
  }
}

After the customer completes payment, CamelPay calls your account's topup webhook and the tokens are credited to your wallet instantly.

# Feedback widget

Add a non-intrusive feedback bubble to your website in minutes. The widget is powered by a publishable key and submits feedback directly to your TumaMaoni account — no backend needed.

Install

Add this to your page, replacing apiKey with your publishable key:

<script src="https://tumamaoni.com/widget.js" async></script>
<script>
  TumaMaoni.init({
    apiKey: 'TM-pub-your_publishable_key',
    appName: 'Tumamaoni',
    auto: { enabled: true, frequency: 'twice_week' }
  });
</script>

Event-triggered prompts

Ask for feedback after a specific action (for example after checkout):

// call after a user does something
TumaMaoni.askFeedback('Checkout');

Auto-prompt frequency

# Webhooks

TumaMaoni doesn't need you to poll for payment status — when your mobile money topup is confirmed, your token wallet is credited automatically.

Topup webhook

When a topup payment succeeds through CamelPay, TumaMaoni receives a webhook at https://tumamaoni.com/api/token_topup_webhook.php and credits the customer's wallet. You never have to write code for this — it happens automatically on our side.

# API reference

Complete list of endpoints. Base URL: https://tumamaoni.com/api/v2. Every paid endpoint costs 1 token.

Wallet & key management free

Feedback 1 token each

Analytics 1 token each

Data 1 token each

Submit feedback — fields

List feedback — query filters

Example — list feedback

curl "https://tumamaoni.com/api/v2/feedbacks?page=1&per_page=20&rating=5" \
  -H "Authorization: Bearer TM-secret-your_key_here"

# Error handling

Errors are always returned as JSON with a success: false flag and a human-readable error message. Failed paid requests are automatically refunded.

{
  "success": false,
  "error": "Insufficient token balance. Top up to continue.",
  "code": "insufficient_tokens",
  "balance": 0,
  "topup_url": "https://tumamaoni.com/api",
  "tokens_per_request": 1
}

Status codes

Refunds

Tokens are charged when a paid request begins and refunded automatically if the request ends with a 4xx or 5xx status. Refunds appear in your Token history as refund transactions.

# Rate limits

Each API key has a daily request budget that resets at midnight (Tanzania time). Limits apply per key, not per account. If you have paid for tokens, there are no rate limits.

When a free key hits its cap, the API returns 429 with the limit in the error payload. Zero-token endpoints (keys, balance, usage, topup) count toward your daily cap too, but never cost tokens.

# Support

We're here to help you integrate.

• Developer portal: tumamaoni.com/api — keys, billing, usage analytics
• Documentation: tumamaoni.com/docs/api
• Email: support@tumamaoni.com
• Business dashboard: tumamaoni.com/dashboard