Integration Documentation
This is a public documentation preview. API documentation can be reviewed without an account. API keys, live testing, and production access require an authorized Indemption or BuzzWorks account. Endpoint availability may depend on account configuration and enabled features.
Overview
Indemption APIs allow approved external systems to validate wallet passes, redeem offers, and access structured campaign activity. The public documentation below is provided so developers and technical evaluators can understand how integrations are designed before creating an account.
Base URL
https://api.buzzworksai.com/api/public/v1
Documentation preview only. Production endpoints may require feature enablement for your account.
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. Keys can be limited to specific actions such as wallet_pass:validate or wallet_pass:redeem.
- Keys are created inside an authorized account when API key management is enabled.
- Keys should be stored securely on server-side systems.
- Keys can be rotated or revoked if credentials are exposed or integrations change.
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
| Code | Meaning |
|---|---|
| 200 | Request completed successfully |
| 400 | Missing or invalid request data |
| 401 | Missing or invalid API key |
| 403 | API key lacks permission or authorized scope |
| 404 | Resource not found |
| 409 | Conflict, such as already redeemed when a single-use pass is submitted again |
| 429 | Too many requests |
| 500 | Unexpected server error |
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.