Integration Documentation

Overview

Indemption APIs allow approved external systems to start Loops, validate wallet passes, redeem offers, and access structured campaign activity. Choose the surface that matches your job:

• UOCL Loop Start webhook — CURRENT inbound path for Ride / Loop launches (POST …/webhook/ride-start).
• Wallet pass validate / redeem — public REST preview under the base URL below (feature enablement required; not the Loop Start contract).

Planned public REST base URL

https://api.buzzworksai.com/api/public/v1

Wallet sections on this page are documentation preview only. For inbound Loop Start, follow the Loop Start guide — do not POST Loop payloads to /api/public/v1.

Authentication

Production API calls require an API key created inside an authorized Indemption or BuzzWorks account.

Header example

Authorization: Bearer bw_live_your_api_key_here
Content-Type: application/json

API Keys

API keys are designed to be scoped by permission and authorized client context. Planned scopes include actions such as wallet_pass:validate or wallet_pass:redeem, plus Loop Start when key management ships.

• Keys should be stored securely on server-side systems.
• Keys can be rotated or revoked if credentials are exposed or integrations change.
• Self-serve create / rotate / delete is live on Connections → API Keys (bw_live_… keys, shown once at create/rotate).

Wallet Pass Validation

Endpoint

POST /wallet-passes/validate

Required permission: wallet_pass:validate

Example request

{
  "pass_token": "abc123"
}

Barcode alternative:

{
  "barcode_value": "abc123"
}

Example valid response

{
  "success": true,
  "valid": true,
  "status": "active",
  "wallet_pass": {
    "id": "pass-instance-id",
    "campaign_id": "campaign-id",
    "mail_owner_id": "mail-owner-id",
    "offer_name": "Spring Offer",
    "expires_at": "2026-12-31T23:59:59Z",
    "redeemed_at": null
  }
}

Example already redeemed response

{
  "success": true,
  "valid": false,
  "status": "redeemed",
  "message": "Wallet pass has already been redeemed."
}

Wallet Pass Redemption

Endpoint

POST /wallet-passes/redeem

Required permission: wallet_pass:redeem

Example request

{
  "pass_token": "abc123",
  "redemption_location": "Store 102",
  "redemption_reference": "POS-ORDER-98765",
  "redeemed_by": "cashier-12",
  "notes": "Redeemed at checkout"
}

Example successful response

{
  "success": true,
  "redeemed": true,
  "status": "redeemed",
  "wallet_pass": {
    "id": "pass-instance-id",
    "redeemed_at": "2026-06-08T14:25:00Z",
    "redemption_location": "Store 102",
    "redemption_reference": "POS-ORDER-98765"
  }
}

Example already redeemed response

{
  "success": true,
  "redeemed": false,
  "status": "already_redeemed",
  "message": "Wallet pass was already redeemed."
}

Response Codes

Security Notes

Do not expose API keys in browser JavaScript. API keys should be used from secure server-side systems, POS middleware, approved mobile backends, or controlled integration services.

• Use HTTPS for all production API calls.
• Scope keys to the minimum permissions required.
• Rotate keys when staff, vendors, or integration partners change.
• Log and monitor API usage for auditing and troubleshooting.

Versioning

Public API endpoints are versioned. The first public version uses /v1 in the request path. Future versions may add new fields or endpoints while preserving documented behavior for existing integrations where practical.

Support

For integration questions, setup assistance, or partner discussions, contact mail@buzzworksai.com.

Contact Integration Support

← Back to APIs & Integrations · Start a Loop with the API