API reference

Returns: 200 Account. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/account \
  -H "Authorization: Bearer jusa_sk_test_…"

Owners and admins only (a key counts as its maker). Scope: account:manage.

Returns: 200 Account. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/account \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"statement_descriptor": "ACME SURVEYS", "support_phone": "0772123456"}'

Scope: account:manage.

Returns: 200 InviteList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/invites \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: account:manage.

Returns: 200 Invite. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/invites/{invite_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Owners and admins only. Scope: account:manage.

Returns: 200 Invite. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/invites/{invite_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: account:manage.

Returns: 200 MemberList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/members \
  -H "Authorization: Bearer jusa_sk_test_…"

An invitation, pending until the person signs in and accepts it from their dashboard (it lapses after 14 days). Until then they are not a member and see nothing of the account. Scope: account:manage.

Returns: 201 Invite. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/members \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "role": "developer"}'

Scope: account:manage.

Returns: 200 Member. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/members/{member_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: account:manage.

Returns: 200 Member. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/members/{member_id} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"role": "owner"}'

Scope: account:manage.

Returns: 200 Member. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/members/{member_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Dashboard only (a signed-in person): each organisation you belong to and whether it is a developer organisation.

Returns: 200 OrganisationList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/organisations \
  -H "Authorization: Bearer jusa_sk_test_…"

Dashboard only (a signed-in person): makes the live org and its test-mode twin.

Returns: 201 Account. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/organisations \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Dashboard only (a signed-in person).

Returns: 200 InviteList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/organisations/invites \
  -H "Authorization: Bearer jusa_sk_test_…"

Dashboard only: the person invited, signed in.

Returns: 200 Organisation. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/organisations/invites/{invite_id}/accept \
  -H "Authorization: Bearer jusa_sk_test_…"

Dashboard only: the person invited, signed in.

Returns: 200 Invite. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/organisations/invites/{invite_id}/decline \
  -H "Authorization: Bearer jusa_sk_test_…"

Jusa Credit with runway, sends today, success by network, webhook health and what needs attention. Sections the caller cannot read are null.

Returns: 200 Overview. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/overview \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: account:manage.

Returns: 200 ApiKeyList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/keys \
  -H "Authorization: Bearer jusa_sk_test_…"

The key is in secret, once. The first live key needs accept_terms: true (the API Terms, the Acceptable Use policy and the DPA). No Idempotency-Key: a replay would have to show the secret again. Scope: account:manage.

Returns: 201 ApiKey. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/keys \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"kind": "rk", "label": "survey relay", "scopes": ["rewards:write"]}'

With usage: what it has spent against its caps. Scope: account:manage.

Returns: 200 ApiKey. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/keys/{key_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: account:manage.

Returns: 200 ApiKey. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/keys/{key_id} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Takes effect at once. Scope: account:manage.

Returns: 200 ApiKey. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/keys/{key_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

A new key in secret; the old one (in rolled) works for the grace period. Scope: account:manage.

Returns: 201 ApiKey. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/keys/{key_id}/roll \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

What happened lately (events: sends, rewards, top-ups, batches …), newest first, and, with account:manage, who changed what (the audit log). Pages back with starting_after. Scope: reports:read.

Returns: 200 AccountActivityList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/activity \
  -H "Authorization: Bearer jusa_sk_test_…"

Who (a key, a member, or Jusa staff viewing as you) changed what. Scope: account:manage.

Returns: 200 AuditEventList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/audit-log \
  -H "Authorization: Bearer jusa_sk_test_…"

Kept 30 days. status is a code (402) or a class (4xx). Scope: account:manage.

Returns: 200 RequestLogList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/requests \
  -H "Authorization: Bearer jusa_sk_test_…"

With the masked request and response bodies. Scope: account:manage.

Returns: 200 RequestLog. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/requests/{request_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: catalog:read. Publishable keys may call it (from a browser).

Returns: 200 NetworkList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/networks \
  -H "Authorization: Bearer jusa_sk_test_…"

Face value, always: there is no pricing endpoint. Scope: catalog:read. Publishable keys may call it (from a browser).

Returns: 200 ProductList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/products \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: catalog:read. Publishable keys may call it (from a browser).

Returns: 200 Product. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/products/{product_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Test mode has a simulated list; live data bundles ship in P2. Scope: catalog:read. Publishable keys may call it (from a browser).

Returns: 200 BundleList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/products/{product_id}/bundles \
  -H "Authorization: Bearer jusa_sk_test_…"

Its network and E.164 form. No provider is asked. Scope: lookups:read.

Returns: 200 PhoneLookup. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/lookups/phone \
  -H "Authorization: Bearer jusa_sk_test_…"

The name is masked and the address is the suburb. Rationed: 30 a minute per key and a daily quota per account. 503 zesa_unavailable when ZESA is down. Scope: lookups:read.

Returns: 200 Meter. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/meters/{number} \
  -H "Authorization: Bearer jusa_sk_test_…"

you_pay is always the face value. For ZESA: the units and band now and after the reset, and a strictly confirmed meter that a send carries by passing the quote. Scope: lookups:read.

Returns: 201 Quote. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/quotes \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"product": "zesa-usd", "amount": "10.00", "target": "37261502217"}'

Scope: lookups:read.

Returns: 200 Quote. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/quotes/{quote_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Publishable keys may call it (from a browser).

Returns: 200 Status. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/status \
  -H "Authorization: Bearer jusa_sk_test_…"

The last 7 days by default. Publishable keys may call it (from a browser).

Returns: 200 StatusHistory. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/status/history \
  -H "Authorization: Bearer jusa_sk_test_…"

Anonymised and coarsened: no meter, no order. Scope: lookups:read.

Returns: 200 ZesaObservations. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/zesa/observations \
  -H "Authorization: Bearer jusa_sk_test_…"

Units now versus after the reset on the 1st; with meter, from where that meter stands this month (a meter is rationed like a lookup). POST /v1/quotes also confirms the meter. Scope: lookups:read.

Returns: 200 ZesaRate. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/zesa/quote \
  -H "Authorization: Bearer jusa_sk_test_…"

ZETDC's published bands, what real purchases show a kWh costs, and the cheapest-units rule (the bands reset on the 1st). Public data, the same in test and live mode. Scope: catalog:read.

Returns: 200 ZesaRate. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/zesa/rate \
  -H "Authorization: Bearer jusa_sk_test_…"

The sparkline of the observed rate and where it changed. Scope: catalog:read.

Returns: 200 ZesaSeries. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/zesa/series \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: sends:read.

Returns: 200 SendList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/sends \
  -H "Authorization: Bearer jusa_sk_test_…"

Always async: the send is written and charged, then dispatched; webhooks and GET tell the rest. validate_only: true runs every check and writes nothing (200, no Idempotency-Key needed). A client_reference already used returns that send (200). An agent key over its threshold or to a new target gets 202 with an agent_approval instead. Scope: sends:write. Moves money: an Idempotency-Key is required.

Returns: 200 Send or SendValidation · 202 Send or AgentApproval. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/sends \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"product": "airtime-usd", "target": "0772123456", "amount": "1.00", "client_reference": "order-8812"}'

Scope: sends:read.

Returns: 200 Send. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/sends/{send_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

When it went to the provider, and each time Hot Recharge was asked what it recorded (outcomes only). Scope: sends:read.

Returns: 200 SendAttemptList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/sends/{send_id}/attempts \
  -H "Authorization: Bearer jusa_sk_test_…"

A scheduled send, or one still waiting to go: the credit comes back (cancelled_credited). 409 already_sent once it has gone. Scope: sends:write.

Returns: 200 Send. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/sends/{send_id}/cancel \
  -H "Authorization: Bearer jusa_sk_test_…"

Only while it has not gone out (queued while ZESA is down, or scheduled). The new meter is confirmed now when ZESA answers, else before the send goes out. Audited, and send.meter_changed goes to every endpoint. Scope: sends:write.

Returns: 200 Send. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/sends/{send_id}/meter \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"meter": "37261502217"}'

JSON, or ?format=pdf for the same receipt as a PDF. The token is masked without tokens:read. Scope: sends:read.

Returns: 200 Receipt. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/sends/{send_id}/receipt \
  -H "Authorization: Bearer jusa_sk_test_…"

Only to the phone and email it went to first. Rate-limited. Scope: sends:write.

Returns: 202 TokenResend. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/sends/{send_id}/resend-token \
  -H "Authorization: Bearer jusa_sk_test_…"

A terminal failed send (failed_credited or failed) only, sent again as a new send charged now, with retry_of. Hot Recharge is asked about the first send before anything is resent: delivered after all is 409 send_delivered_late, no answer is 503 provider_unavailable. 409 send_not_retryable from any other state, for a card checkout's send, and for a send already retried. Scope: sends:write. Moves money: an Idempotency-Key is required.

Returns: 202 Send. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/sends/{send_id}/retry \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

Scope: sends:read.

Returns: 200 DisputeList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/disputes \
  -H "Authorization: Bearer jusa_sk_test_…"

Opens a staff case. A delivered send is never reversed. Scope: sends:write.

Returns: 201 Dispute. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/disputes \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"send": "snd_\u2026", "reason": "token_not_received", "evidence": "Customer says no SMS came."}'

Scope: sends:read.

Returns: 200 Dispute. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/disputes/{dispute_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: sends:read.

Returns: 200 BatchList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/batches \
  -H "Authorization: Bearer jusa_sk_test_…"

Up to 10,000 items (JSON or CSV). Credit is reserved at once by default; above the account's approval threshold it waits for a second person. Scope: batches:write. Moves money: an Idempotency-Key is required.

Returns: 202 Batch. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/batches \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title": "October allowance", "items": [{"target": "0772123456", "amount": "5.00"}, {"target": "0712345678", "amount": "5.00"}]}'

Scope: sends:read.

Returns: 200 Batch. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/batches/{batch_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

By an owner or admin other than the batch's maker. Scope: batches:write. Moves money: an Idempotency-Key is required.

Returns: 200 Batch. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/batches/{batch_id}/approve \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

Items not yet sent are cancelled; unspent reserved credit is released. Scope: batches:write.

Returns: 200 Batch. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/batches/{batch_id}/cancel \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: sends:read.

Returns: 200 BatchItemList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/batches/{batch_id}/items \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: sends:read.

Returns: 200 CSV. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/batches/{batch_id}/results.csv \
  -H "Authorization: Bearer jusa_sk_test_…"

A new batch, charged again. Each failed item is retried once. Scope: batches:write. Moves money: an Idempotency-Key is required.

Returns: 202 Batch. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/batches/{batch_id}/retry-failed \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Per-line validity, totals, whether the credit and the provider float suffice. Scope: batches:write.

Returns: 200 BatchPreview. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/batches/preview \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "October allowance", "items": [{"target": "0772123456", "amount": "5.00"}, {"target": "0712345678", "amount": "5.00"}]}'

Scope: sends:read.

Returns: 200 ScheduleList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/schedules \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: schedules:write.

Returns: 201 Schedule. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Monthly allowance", "cadence": "monthly", "day_of_month": 1, "hour": 8, "minute": 0, "group": "grp_\u2026", "product": "airtime-usd", "amount": "5.00"}'

Scope: sends:read.

Returns: 200 Schedule. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: schedules:write.

Returns: 200 Schedule. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Monthly allowance", "cadence": "monthly", "day_of_month": 1, "hour": 8, "minute": 0, "group": "grp_\u2026", "product": "airtime-usd", "amount": "5.00"}'

Scope: schedules:write.

Returns: 200 DeletedSchedule. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

From today to 60 days on by default (YYYY-MM-DD). Scope: sends:read.

Returns: 200 ScheduleOccurrenceList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/occurrences \
  -H "Authorization: Bearer jusa_sk_test_…"

ran with its batch once it has gone out. Scope: sends:read.

Returns: 200 ScheduleOccurrence. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/occurrences/{day} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: schedules:write.

Returns: 200 ScheduleOccurrence. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/occurrences/{day} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

The other run (this schedule's on into, or schedule's) sends both amounts in one recharge per person, and this one is combined. Same people, currency and cost centre only. Reset undoes it. Scope: schedules:write.

Returns: 200 ScheduleOccurrence. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/occurrences/{day}/combine \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"into": "2026-11-02"}'

Scope: schedules:write.

Returns: 200 ScheduleOccurrence. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/occurrences/{day}/move \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"to": "string"}'

Scope: schedules:write.

Returns: 200 ScheduleOccurrence. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/occurrences/{day}/reset \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: schedules:write.

Returns: 200 ScheduleOccurrence. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/occurrences/{day}/skip \
  -H "Authorization: Bearer jusa_sk_test_…"

A run is a batch: it reserves its total and may wait for approval. Scope: schedules:write. Moves money: an Idempotency-Key is required.

Returns: 202 Batch. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/run-now \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Scope: schedules:write.

Returns: 200 ScheduleRunPreview. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/schedules/{schedule_id}/run-now/preview \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:read.

Returns: 200 CostCenterList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/cost-centers \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:write.

Returns: 201 CostCenter. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/cost-centers \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing", "gl_code": "6100", "monthly_budget": "250.00"}'

Scope: recipients:read.

Returns: 200 CostCenter. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/cost-centers/{cost_center_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:write.

Returns: 200 CostCenter. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/cost-centers/{cost_center_id} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing", "gl_code": "6100", "monthly_budget": "250.00"}'

Scope: recipients:read.

Returns: 200 CostCenterSpend. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/cost-centers/{cost_center_id}/spend \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:read.

Returns: 200 GroupList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/groups \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:write.

Returns: 201 Group. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/groups \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Field team"}'

Scope: recipients:read.

Returns: 200 Group. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/groups/{group_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:write.

Returns: 200 Group. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/groups/{group_id} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Field team"}'

Scope: recipients:write.

Returns: 200 DeletedGroup. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/groups/{group_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:write.

Returns: 200 Group. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/groups/{group_id}/members \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"recipients": []}'

Scope: recipients:write.

Returns: 200 Group. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/groups/{group_id}/members \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"recipients": []}'

Scope: recipients:read.

Returns: 200 RecipientList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/recipients \
  -H "Authorization: Bearer jusa_sk_test_…"

Upserts on external_id, then phone: 201 when made, 200 when updated. Scope: recipients:write.

Returns: 200 Recipient · 201 Recipient. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/recipients \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_123", "name": "Tendai Moyo", "phone": "0772123456"}'

Scope: recipients:read.

Returns: 200 Recipient. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/recipients/{recipient_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:write.

Returns: 200 Recipient. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/recipients/{recipient_id} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_123", "name": "Tendai Moyo", "phone": "0772123456"}'

Deactivates. With erase=true, erases their data and keeps the history masked; refused (409 erasure_deferred) while a send is in flight or a schedule is active. Scope: recipients:write.

Returns: 200 DeletedRecipient or Recipient. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/recipients/{recipient_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:read.

Returns: 200 RecipientBalance. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/recipients/{recipient_id}/balance \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: sends:read.

Returns: 200 SendList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/recipients/{recipient_id}/sends \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: recipients:read.

Returns: 200 RecipientSpend. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/recipients/{recipient_id}/spend \
  -H "Authorization: Bearer jusa_sk_test_…"

Everything sent to them in a period (this month by default; YYYY-MM-DD, inclusive), totalled by currency and outcome, with each send (up to 500). Scope: recipients:read.

Returns: 200 RecipientStatement. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/recipients/{recipient_id}/statement \
  -H "Authorization: Bearer jusa_sk_test_…"

Up to 5,000, as JSON rows or CSV. Scope: recipients:write.

Returns: 200 RecipientImport. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/recipients/bulk \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Scope: rewards:read.

Returns: 200 ProgramList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/programs \
  -H "Authorization: Bearer jusa_sk_test_…"

The completions HMAC secret is shown once, here. A reserve program sets its whole budget aside (402 when the credit is short). Scope: programs:manage.

Returns: 201 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Household survey Q4", "currency": "USD", "default_amount": "0.50", "budget": "500.00", "funding": "reserve", "per_recipient": {"lifetime": 1}}'

Scope: rewards:read.

Returns: 200 Program. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/programs/{program_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: programs:manage.

Returns: 200 Program. Errors: the envelope.

curl -X PATCH https://jusa.localhost.co.zw/dev/v1/programs/{program_id} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

The same as POST …/close. Scope: programs:manage.

Returns: 200 Program. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/programs/{program_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: programs:manage.

Returns: 200 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/activate \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: programs:manage.

Returns: 200 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/close \
  -H "Authorization: Bearer jusa_sk_test_…"

For survey tools that can sign a webhook but hold no key: Jusa-Signature: t=<unix>,v1=<hex HMAC-SHA256(program secret, "{t}.{raw body}")>, within 5 minutes. completion_id (or ref) is required; a repeat returns the first reward (200).

Returns: 200 Reward · 201 Reward. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/completions \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Without an amount: everything no escrow or unclaimed link has earmarked. Scope: programs:manage. Moves money: an Idempotency-Key is required.

Returns: 200 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/defund \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Scope: programs:manage. Moves money: an Idempotency-Key is required.

Returns: 200 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/fund \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount": "5.00"}'

Scope: programs:manage.

Returns: 200 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/pause \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: programs:manage.

Returns: 200 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/resume \
  -H "Authorization: Bearer jusa_sk_test_…"

The old secret keeps working for 24 hours. Scope: programs:manage.

Returns: 200 Program. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/roll-secret \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:read.

Returns: 200 RewardList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/rewards \
  -H "Authorization: Bearer jusa_sk_test_…"

The seed primitive: caps, fraud rules and budget under one lock, then a send or a link. The same completion_id again returns the first reward (200). A refusal writes nothing, so it can be retried. Scope: rewards:write. Moves money: an Idempotency-Key is required.

Returns: 200 Reward · 201 Reward · 202 AgentApproval. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/rewards \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"program": "prg_\u2026", "recipient": {"external_id": "resp-8812", "phone": "0771230000"}, "completion_id": "8812", "metadata": {"survey": "form-hh-q4"}}'

Scope: rewards:read.

Returns: 200 Reward. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/rewards/{reward_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Optionally for less. Scope: rewards:write. Moves money: an Idempotency-Key is required.

Returns: 200 Reward. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/rewards/{reward_id}/release \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Its budget goes back to the program. Scope: rewards:write.

Returns: 200 Reward. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/rewards/{reward_id}/void \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:read.

Returns: 200 RewardLinkList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/reward-links \
  -H "Authorization: Bearer jusa_sk_test_…"

One link, or a list when count is over 1 (up to 500). Each has a url, a token and a QR code. Scope: rewards:write.

Returns: 201 RewardLink or RewardLinkList. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/reward-links \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"program": "prg_\u2026", "count": 10, "bind": "otp", "label": "enumerator-7"}'

Scope: rewards:read.

Returns: 200 RewardLink. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/reward-links/{link_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:write.

Returns: 200 RewardLink. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/reward-links/{link_id}/revoke \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:read.

Returns: 200 BlockedTargetList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/blocklist \
  -H "Authorization: Bearer jusa_sk_test_…"

Live mode only. Scope: account:manage.

Returns: 201 BlockedTarget. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/blocklist \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"target": "string"}'

Scope: rewards:read.

Returns: 200 BlockedTarget. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/blocklist/{entry_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: account:manage.

Returns: 200 BlockedTarget. Errors: the envelope.

curl -X DELETE https://jusa.localhost.co.zw/dev/v1/blocklist/{entry_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:read.

Returns: 200 ReviewList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/reviews \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:read.

Returns: 200 Review. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/reviews/{review_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Re-checks the caps and budget under lock, then sends. Scope: programs:manage. Moves money: an Idempotency-Key is required.

Returns: 200 Review. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/reviews/{review_id}/approve \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Scope: programs:manage.

Returns: 200 Review. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/reviews/{review_id}/reject \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Scope: rewards:read.

Returns: 200 ActivityList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/activities \
  -H "Authorization: Bearer jusa_sk_test_…"

Feeds the program rules; matches says what it triggered. activity_id dedupes for good (200). Scope: rewards:write.

Returns: 200 Activity · 201 Activity. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/activities \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "ext:user_123", "name": "lesson.completed", "activity_id": "log-9981"}'

Scope: rewards:read.

Returns: 200 Activity. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/activities/{activity_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:read. Publishable keys may call it (from a browser).

Returns: 200 CheckinList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/checkins \
  -H "Authorization: Bearer jusa_sk_test_…"

Publishable keys may call it from the browser. Publishable keys may call it (from a browser).

Returns: 201 Checkin. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/checkins \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"link": "string", "lat": 1, "lng": 1, "phone": "0772123456"}'

Scope: rewards:read.

Returns: 200 ProgramRuleList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/rules \
  -H "Authorization: Bearer jusa_sk_test_…"

The whole set: rules left out are switched off. lottery and prize_draw are refused. Scope: programs:manage.

Returns: 200 ProgramRuleList. Errors: the envelope.

curl -X PUT https://jusa.localhost.co.zw/dev/v1/programs/{program_id}/rules \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"rules": []}'

Scope: rewards:read.

Returns: 200 ReferralList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/referrals \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: rewards:write.

Returns: 200 Referral · 201 Referral. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/referrals \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"program": "string", "referrer": "string", "referee": "string"}'

Scope: rewards:read.

Returns: 200 Referral. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/referrals/{referral_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Pays the direct referrer (depth 1), in escrow by default. Scope: rewards:write. Moves money: an Idempotency-Key is required.

Returns: 200 Referral. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/referrals/{referral_id}/qualify \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

For publishable keys (the widget). Publishable keys may call it (from a browser).

Returns: 200 RewardLinkClaim. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/claims/{token} \
  -H "Authorization: Bearer jusa_sk_test_…"

Publishable keys may call it (from a browser).

Returns: 200 RewardLinkClaim · 201 RewardLinkClaim. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/claims/{token} \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"phone": "0772123456"}'

Publishable keys may call it (from a browser).

Returns: 200 ClaimCode. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/claims/{token}/code \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"phone": "0772123456"}'

Returns: 200 AgentApprovalList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/approvals \
  -H "Authorization: Bearer jusa_sk_test_…"

Returns: 200 AgentApproval. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/approvals/{approval_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Dashboard only: an owner or admin, with their payment PIN.

Returns: 200 AgentApproval. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/approvals/{approval_id}/approve \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Dashboard only.

Returns: 200 AgentApproval. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/approvals/{approval_id}/reject \
  -H "Authorization: Bearer jusa_sk_test_…"

Agent keys only. Tools: send_airtime, buy_zesa, confirm_meter, create_reward, get_balance, get_send, list_products. 202 with no body answers a notification; a message that is not JSON-RPC is a JSON-RPC error with status 400.

Returns: 200 JsonRpcResponse · 202 no body · 400 JsonRpcResponse. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/mcp \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Scope: credit:read.

Returns: 200 Credit. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/credit \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: credit:read.

Returns: 200 CreditAlerts. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/credit/alerts \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: account:manage.

Returns: 200 CreditAlerts. Errors: the envelope.

curl -X PUT https://jusa.localhost.co.zw/dev/v1/credit/alerts \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Scope: credit:read.

Returns: 200 CreditReservationList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/credit/reservations \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: credit:read.

Returns: 200 TopupList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/credit/topups \
  -H "Authorization: Bearer jusa_sk_test_…"

pesepay: send a person to redirect_url; the card fee is paid by the payer. bank_transfer: our bank details and a reference to quote. Any amount; spendable once paid. Scope: credit:topup. Moves money: an Idempotency-Key is required.

Returns: 201 Topup. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/credit/topups \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"method": "pesepay", "amount": "100.00", "currency": "USD"}'

Scope: credit:read.

Returns: 200 Topup. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/credit/topups/{topup_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: credit:read.

Returns: 200 CreditTransactionList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/credit/transactions \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: credit:read.

Returns: 200 CreditTransaction. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/credit/transactions/{transaction_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: credit:read.

Returns: 200 Statement. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/statements \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: credit:read.

Returns: 200 CSV. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/statements.csv \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: credit:read.

Returns: 200 no body. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/statements.pdf \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: sends:read.

Returns: 200 CheckoutSessionList. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/checkout-sessions \
  -H "Authorization: Bearer jusa_sk_test_…"

Your user pays by card on Pesepay (Jusa is the merchant of record and the card fee is the payer's); the send is booked to you. A repeated client_reference returns the first session (200). Scope: sends:write. Moves money: an Idempotency-Key is required.

Returns: 200 CheckoutSession · 201 CheckoutSession. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/checkout-sessions \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type": "zesa", "target": "37261502217", "amount": "20.00", "currency": "USD", "token_phone": "0772123456", "success_url": "https://example.com/thanks", "cancel_url": "https://example.com/basket"}'

Scope: sends:read.

Returns: 200 CheckoutSession. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/checkout-sessions/{session_id} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: sends:write.

Returns: 200 CheckoutSession. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/checkout-sessions/{session_id}/meter \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"meter": "37261502217"}'

Scope: workforce:admin.

Returns: 200 WorkforceAccess. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/workforce/access \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: workforce:admin.

Returns: 200 WorkforceSendResult. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/workforce/allocate \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"kind": "airtime", "product_ref": "airtime-usd", "cost_center_id": 3, "idempotency_key": "stipend-2026-10", "lines": [{"recipient_id": 12, "amount": "2.00"}]}'

Scope: workforce:admin.

Returns: 200 WorkforcePreview. Errors: the envelope.

curl -X POST https://jusa.localhost.co.zw/dev/v1/workforce/allocate/preview \
  -H "Authorization: Bearer jusa_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"kind": "airtime", "product_ref": "airtime-usd", "cost_center_id": 3, "idempotency_key": "stipend-2026-10", "lines": [{"recipient_id": 12, "amount": "2.00"}]}'

Scope: workforce:admin.

Returns: 200 WorkforceBatchPage. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/workforce/batches \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: workforce:admin.

Returns: 200 WorkforceBatch. Errors: the envelope.

curl https://jusa.localhost.co.zw/dev/v1/workforce/batches/{reference} \
  -H "Authorization: Bearer jusa_sk_test_…"

Scope: workforce:admin.