Handle proof
Once an Operator submits proof, approve to release escrow, reject with a structured reason to open a dispute, or cancel before acceptance to refund.
When an Operator submits proof, the task reaches proof_submitted, then verifying as the AI verification layer produces a report. What happens to the money is your decision — release it, freeze it, or refund it. This guide covers the three settlement actions and when to reach for each.
Each action is a mutating call and requires an Idempotency-Key. None of them run through an AI model — approval and rejection are deterministic state transitions you drive, and both are valid only while the task is verifying.
Read the report first
Fetch the verification report before you settle. It lists the checks that ran, what they found, and a confidence score.
curl https://api.hannu.africa/v1/tasks/task_8f21/proof \
-H "Authorization: Bearer $HANNU_KEY"Approve — release escrow
If the proof holds up, approve. Escrow releases to the Operator, the task reaches approved (settling to paid once the payout completes), and the ledger records the transfer.
curl -X POST https://api.hannu.africa/v1/tasks/task_8f21/approve \
-H "Authorization: Bearer $HANNU_KEY" \
-H "Idempotency-Key: $(uuidgen)"Use approve when the report's checks pass and the work matches what you asked for.
Reject — open a dispute, freeze escrow
If the proof is wrong, reject it with a structured reason. This freezes escrow — funds stay locked, paid to neither side — and opens a dispute for resolution. The handler reads reason only, so put the full context in that field.
curl -X POST https://api.hannu.africa/v1/tasks/task_8f21/reject \
-H "Authorization: Bearer $HANNU_KEY" \
-H "Idempotency-Key: $(uuidgen)"The dispute emits dispute.opened, and its outcome emits dispute.resolved. Depending on the resolution, escrow either releases to the Operator or refunds to your wallet — a resolved terminal state, either way. See Escrow and the ledger.
A structured reason is what turns a rejection into a reviewable dispute. Don't reject without one — an empty or vague reason gives the dispute nothing to weigh.
Cancel — refund before acceptance
If you no longer need a task and no Operator has accepted it yet, cancel. Escrow refunds to your wallet in full.
curl -X POST https://api.hannu.africa/v1/tasks/task_8f21/cancel \
-H "Authorization: Bearer $HANNU_KEY" \
-H "Idempotency-Key: $(uuidgen)"Cancel is only available before acceptance. Once an Operator is working the task, settling means approving or rejecting the proof they submit.
Which action, when
| Situation | Action | Escrow |
|---|---|---|
| Proof passes, work matches the request | Approve | Released to Operator |
| Proof is wrong or incomplete | Reject with a reason | Frozen, dispute opens |
| No longer needed, not yet accepted | Cancel | Refunded to your wallet |
There is no pilot webhook for Operator proof submission. Poll GET /v1/tasks/:id (or /proof) and act when the task reaches verifying — the state approve and reject operate from. The task.submitted and task.review_required events fire earlier, at creation and safety screening, not on proof. See the event catalogue.