Docs menuSurveyCTO guide

Build

SurveyCTO guide

A form webhook posts each submission to a relay that rewards it.

How it fits together

SurveyCTO can post each submission to a URL, but it cannot sign a request the way Jusa's completions endpoint wants or hold a secret key safely. So a small relay of yours sits between them: SurveyCTO posts to it, it checks the post really came from your form, and it calls POST /rewards, keyed on the submission so each is paid once, forever.

  1. Make a program (dashboard or POST /programs) with the budget, the amount and per_recipient={"lifetime": 1} if each person is paid once.
  2. Make a restricted key with only rewards:write, and give it to the relay. If it ever leaks, it can reward from that program's budget and do nothing else.
  3. Add a question for the respondent's mobile number to the form (and their meter, if you pay ZESA).

In SurveyCTO

  1. In your server console, set up a webhook for the form (SurveyCTO's data publishing to a URL), pointing at your relay, for example https://relay.example.org/surveycto?token=3f9c…. The long random token in the URL is how the relay knows the post is yours.
  2. Each submission arrives as JSON with your field names and SurveyCTO's own fields, among them KEY (uuid:…), unique per submission. That is the completion_id.
  3. Keep the phone field unencrypted, or the relay cannot read it.

The relay

relay.py (Flask)
import hmac
import logging
import os
from http import HTTPStatus

from flask import Flask, abort, request

import jusa

logger = logging.getLogger(__name__)
jusa.api_key = os.environ["JUSA_REWARDS_KEY"]  # jusa_rk_… with rewards:write only
SURVEY_PROGRAM_ID = os.environ["JUSA_PROGRAM"]
# Worth SurveyCTO posting again: nothing was charged, and the same keys never pay twice.
TRY_AGAIN_LATER = (jusa.InsufficientCreditError, jusa.RateLimitError, jusa.ProviderUnavailableError,
                   jusa.APIConnectionError, jusa.APIError)

app = Flask(__name__)


@app.post("/surveycto")
def surveycto():
    if not hmac.compare_digest(request.args.get("token", ""), os.environ["RELAY_TOKEN"]):
        abort(HTTPStatus.FORBIDDEN)
    surveycto_submission = request.get_json()
    submission_id = surveycto_submission["KEY"]  # uuid:…
    try:
        jusa.Reward.create(
            program=SURVEY_PROGRAM_ID,
            recipient={"phone": surveycto_submission["phone"]},
            completion_id=submission_id,
            idempotency_key=f"scto-{submission_id}",
        )
    except TRY_AGAIN_LATER as temporary_error:
        logger.warning("SurveyCTO will post %s again: %s [%s]", submission_id, temporary_error.code,
                       temporary_error.request_id)
        return "", HTTPStatus.SERVICE_UNAVAILABLE
    except jusa.JusaError as refusal:
        # A cap or a blocked number is final for this submission: answer 2xx so SurveyCTO stops.
        logger.warning("Jusa refused %s: %s [%s]", submission_id, refusal.code, refusal.request_id)
    return "", HTTPStatus.OK

The same rules as any relay: a repeat is one reward, a refusal is final (answer 2xx), and 5xx is only for what trying again can fix: an unreachable Jusa, or Jusa Credit that ran out (nothing was charged).

Paying ZESA instead

Add a meter question and a token phone: recipient={"meter": surveycto_submission["meter"], "token_phone": surveycto_submission["phone"]}, and let the program's choices include zesa. The meter is confirmed with ZESA before anything is charged.