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.
- Make a program (dashboard or
POST /programs) with the budget, the amount andper_recipient={"lifetime": 1}if each person is paid once. - 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. - Add a question for the respondent's mobile number to the form (and their meter, if you pay ZESA).
In SurveyCTO
- 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 randomtokenin the URL is how the relay knows the post is yours. - Each submission arrives as JSON with your field names and SurveyCTO's own fields, among them
KEY(uuid:…), unique per submission. That is thecompletion_id. - Keep the phone field unencrypted, or the relay cannot read it.
The relay
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.