Developers

Send a survey from your own systems in one call

A REST API with keys you control, event-triggered surveys, and signed webhooks for every completed response, payout and alert.

Open the API reference Ask for a sandbox

API keys

Create keys in the console under Settings, Developers. The full key is shown once; revoke it at any time. Keys are scoped to your account.

Triggers

Invite a customer to a survey the moment something happens: a transaction, a delivery, the end of a support call.

Webhooks

Get completed responses, successful payouts and tracker alerts pushed to your endpoint, signed and retried.

Triggers

Event-triggered surveys

POST to /api/v1/triggers with your API key. The person is invited right away on the survey’s channel.

Consent built in. If the person isn’t already in the panel, send the consent you collected (consent.source), otherwise the call is refused.
No survey fatigue. One trigger per phone number per survey in 24 hours.
Safe to retry. The same external_ref never invites twice.
Rate limited per key, with a Retry-After header when you go too fast.

# Invite a customer right after a transaction
curl -X POST https://api.smartsurvafrica.com/api/v1/triggers \
  -H "X-Api-Key: ss_xxxxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "survey_id": "3f6c...",
    "phone": "+233244777123",
    "external_ref": "txn-48213",
    "attributes": {"branch": "Osu", "product": "mobile-app"},
    "consent": {"source": "app-terms-v3"}
  }'

# 201 Created
{"trigger_id": "...", "invitation_id": "...", "status": "invited",
 "channel": "whatsapp", "external_ref": "txn-48213", "duplicate": false}

Webhooks

Answers delivered to your systems

Add an endpoint in the console and pick the events. Each delivery is a JSON POST signed with your webhook secret.

Webhook events
Event	When
`response.completed`	A respondent finished a survey (answers by question key, receipt id, your `external_ref`)
`payout.succeeded`	An incentive was paid
`alert`	A tracker alert or stop-rule alert fired

Header X-SmartSurv-Signature: sha256=<hex>: an HMAC-SHA256 of the raw body
Any 2xx answer is success; anything else is retried with backoff for about two hours
A delivery log in the console shows every attempt
No phone numbers or names in payloads

# Verify a delivery (Python)
import hmac, hashlib

def verified(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

// Verify a delivery (Node.js)
const crypto = require('crypto');

function verified(secret, rawBody, header) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

# Body of a response.completed delivery
{"id": "...", "event": "response.completed", "created_at": "...",
 "data": {"survey_id": "...", "survey_title": "Post-transaction NPS",
          "receipt_id": "R-7KQ2M9", "external_ref": "txn-48213",
          "answers": {"nps": "9", "nps__probe": "Fast app"}}}

Reference

The full API

Surveys, results, respondents, payouts, reports and more: everything the console does is in the API. The interactive reference lists every endpoint with request and response shapes.

Base URL

https://api.smartsurvafrica.com/api/v1

Authentication

Triggers use the X-Api-Key header. Console endpoints use a bearer token from sign-in.

Errors

JSON with a detail message. Lists return {"items", "total"}.

Open the API reference