This page covers issuing a reward: create a reward template, then redeem it to a recipient. Organization actions use an org-scoped token. All paths are under https://api.davi.social/api/v1.

A reward template defines what can be issued: points, plus optional content such as a badge, certificate, coupon, voucher, ticket or attachment.

1. Create a reward template

Scope reward:create.

curl -X POST "https://api.davi.social/api/v1/organizations/ORG_SLUG/rewards" \
  -H "Authorization: Bearer ORG_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Check-in Badge",
    "points": 100,
    "supply_total": null,
    "content_config": { "storage_type": "platform" }
  }'

name and points are required. Optional fields are description, category, activity_uuid (links the template to an activity) and supply_total (null is unlimited).

content_config.storage_type sets how the content is produced:

Templates start as drafts. Publish one by PATCHing its status (scope reward:manage):

curl -X PATCH "https://api.davi.social/api/v1/rewards/REWARD_SLUG" \
  -H "Authorization: Bearer ORG_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

status also takes draft, which returns a template to draft while it has no redemptions, and archived, which withdraws it.

2. Redeem a reward

Issue the reward to a recipient with POST /rewards/{reward_slug}/redeem (scope reward:redeem):

curl -X POST "https://api.davi.social/api/v1/rewards/REWARD_SLUG/redeem" \
  -H "Authorization: Bearer ORG_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": { "type": "username", "value": "ada" },
    "scope": "single-use",
    "idempotency_key": "unique-per-redemption"
  }'

Recipients

identifier is an IdentifierRef: { "type": …, "value": … }, where type is card, wallet, username, user_id or link. It resolves to a custodial wallet for someone who has no Davi account yet.

Results

• platform or dynamic: the response is { "status": "completed", "transaction_id": … }.
• external: the response is { "status": "pending", "delivery_uuid": … }. Poll GET /rewards/deliveries/{delivery_uuid} until it reports completed (with a transaction_id) or failed.

The recipient reads the issued content with GET /rewards/transactions/{transaction_id}; see User Rewards.

Issue automatically with triggers

Read this if you want Davi to issue a reward when an event occurs, without a call from your service.

A reward trigger redeems a template when a matching event occurs. Create one with POST /organizations/{organization_slug}/reward-triggers (scope reward:manage):

curl -X POST \
  "https://api.davi.social/api/v1/organizations/ORG_SLUG/reward-triggers" \
  -H "Authorization: Bearer ORG_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reward 5 check-ins",
    "reward_template_uuid": "REWARD_UUID",
    "trigger_scopes": ["activity.checked_in:count:5"],
    "deduplication_window_seconds": 300
  }'

When an activity check-in matches, Davi issues the reward to that user.

Next

• User Rewards: read the rewards a user holds.
• Org Activities: the events that fire triggers.
• Receiving Webhooks: get notified on reward.redeemed.