Overview
KCC sells your event a fixed pool of meal credits. Every voucher is a code; every valid scan at a KCC restaurant (Filini, Larder…) uses one credit, and KCC reports usage from the scans. Your API key identifies your event, so no endpoint takes an event ID.
You send your existing badge QR string as code. Guests carry their normal badge — one QR for check-in and meals.
Leave code out and KCC returns a KCCV-… code plus a QR image URL to print on the badge, show in an app or email.
No integration: generate printed cards in the organiser portal or ask KCC. Download PDF cards, a ZIP of QR images or a CSV.
All three modes draw on the same credit pool. Each voucher gets a profile (e.g. delegate, vip) defined by KCC on your event, which sets its meals, daily limits and restaurants. Creating a voucher reserves its credits; voiding it gives the unused ones back.
Authentication & sandbox
Send your key as a Bearer token on every request:
Authorization: Bearer kcc_live_<32 characters> kcc_live_…— your live key, sent to you separately by your KCC event manager (never shown in the portal). Rotation invalidates the old key immediately.kcc_test_…— your sandbox key, shown in the portal under Integration. It works against a separate sandbox copy of your event with the same profiles and meal types, and its own credit pool.
Keys only work while the event is active. Draft and closed events return 403 event_not_active; closing an event revokes its keys and voids every voucher.
Quick start
1. Read your event setup — profiles, meal types and remaining credits:
curl https://kcc.events.rw/api/v1/event \
-H "Authorization: Bearer kcc_test_YOUR_SANDBOX_KEY" 2. Create two vouchers: one linked to an existing badge code, one issued by KCC:
curl -X POST https://kcc.events.rw/api/v1/vouchers \
-H "Authorization: Bearer kcc_test_YOUR_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-d '{"vouchers":[
{"external_ref":"REG-00421","code":"AHTS26-7F3K9Q","holder_name":"Jane Doe","profile":"delegate"},
{"external_ref":"REG-00422","holder_name":"John Smith","profile":"vip"}
]}' 3. Poll served meals for your own dashboards:
curl "https://kcc.events.rw/api/v1/redemptions?since=2026-11-11T00:00:00%2B02:00&page=1" \
-H "Authorization: Bearer kcc_test_YOUR_SANDBOX_KEY" /api/v1/eventEvent name, dates, status, meal types (with service windows and restaurants), profiles (with entitlements) and the credit pool.
Response 200{
"name": "Africa Health Tech Summit 2026",
"event_code": "EVT-2611-AHTS",
"start_date": "2026-11-11",
"end_date": "2026-11-13",
"status": "active",
"timezone": "Africa/Kigali",
"meal_types": [
{"name": "Lunch", "window_start": "12:00", "window_end": "15:00", "restaurants": ["Filini", "Larder"]},
{"name": "Coffee", "window_start": "08:00", "window_end": "17:00", "restaurants": ["Filini"]}
],
"profiles": [
{
"slug": "delegate", "name": "Delegate", "credits_per_voucher": 3,
"rule": "3 lunches · 1 per day",
"entitlements": [
{"meal_type": "Lunch", "total_uses": 3, "per_day_limit": 1, "restaurants": ["Filini", "Larder"]}
]
}
],
"quota": {"total": 1620, "allocated": 1384, "redeemed": 612, "remaining": 236},
"channels": "both",
"is_sandbox": false
} /api/v1/vouchersCreate or update up to 500 vouchers per request, all-or-nothing.
| Field | Required | Notes |
|---|---|---|
external_ref | Yes | Your registration ID, max 120 characters, unique within the event. Sending the same ref again updates that voucher. |
code | No | Present → Linked: your badge QR string, stored exactly as sent (trimmed, max 255). Absent → KCC issues a KCCV-… code. Codes starting KCCV- are reserved. |
holder_name | No | Shown to restaurant staff on a successful scan. Max 190 characters. |
profile | Yes | A profile slug from GET /event. Custom per-voucher entitlements are not allowed in v1. |
{
"vouchers": [
{
"external_ref": "REG-00421",
"code": "AHTS26-7F3K9Q",
"holder_name": "Jane Doe",
"profile": "delegate"
},
{
"external_ref": "REG-00422",
"holder_name": "John Smith",
"profile": "vip"
}
]
}{
"created": 1,
"updated": 1,
"remaining_credits": 1184,
"vouchers": [
{"external_ref": "REG-00421", "code": "AHTS26-7F3K9Q",
"source": "linked", "qr_png_url": null, ...},
{"external_ref": "REG-00422",
"code": "KCCV-8M2TQ4XW7RJD9KHN3PZE",
"source": "api_issued",
"qr_png_url": "https://kcc.events.rw/qr/KCCV-8M2TQ4XW7RJD9KHN3PZE.png", ...}
]
}Each item in vouchers is the full voucher view (same shape as GET /vouchers/{ref}), so it also carries holder_name, profile, status, entitlements and created_at.
/api/v1/vouchers/{external_ref}One voucher with its entitlements and usage. URL-encode the ref if it contains special characters. Unknown ref → 404 voucher_not_found.
{
"external_ref": "REG-00422",
"code": "KCCV-8M2TQ4XW7RJD9KHN3PZE",
"source": "api_issued",
"holder_name": "John Smith",
"profile": "vip",
"status": "active",
"qr_png_url": "https://kcc.events.rw/qr/KCCV-8M2TQ4XW7RJD9KHN3PZE.png",
"entitlements": [
{"meal_type": "Lunch", "total": 3, "used": 1, "remaining": 2, "per_day_limit": 1},
{"meal_type": "Coffee", "total": 6, "used": 2, "remaining": 4, "per_day_limit": null}
],
"created_at": "2026-11-02T09:14:03+02:00"
} status is active or void. source is linked, api_issued or batch.
/api/v1/vouchers/{external_ref}Change the code (reprinted badge), the holder_name (send null to clear it) or the profile. Send any subset. Uses already made carry over; a profile change reserves or releases only the credit difference.
{"code": "AHTS26-NEW9Q2", "profile": "vip"}{"external_ref": "REG-00421", "code": "AHTS26-NEW9Q2",
"source": "linked", "profile": "vip", ...}Changing the code of a KCC-issued voucher turns it into a linked one. A profile change is refused (422) if the voucher already used more of a meal than the new profile gives.
/api/v1/vouchers/{external_ref}Void the voucher. It stops scanning immediately and its unused credits return to the pool; used credits never come back. Deleting an already-void voucher is a no-op that returns released_credits: 0.
{"voided": true, "external_ref": "REG-00422", "released_credits": 6, "remaining_credits": 1190} /api/v1/redemptions?since=<ISO datetime>&page=<n>Served meals, oldest first, 200 per page. since is ISO 8601 with an offset or Z (e.g. 2026-11-12T00:00:00+02:00; encode + as %2B). Without an offset it is read as Kigali time. Omit it to start from the beginning. Times in responses are Kigali time (UTC+2) with offset.
{
"data": [
{"id": 90211, "external_ref": "REG-00421", "code": "AHTS26-7F3K9Q", "holder_name": "Jane Doe",
"meal_type": "Lunch", "restaurant": "Filini", "served_at": "2026-11-12T12:31:05+02:00"}
],
"since": "2026-11-12T00:00:00+02:00",
"page": 1,
"per_page": 200,
"total": 412,
"next_page": 2
} Keep requesting next_page until it is null. Reversed scans (staff undo) disappear from the feed, so re-read the window you care about rather than accumulating deltas.
Errors
Every error uses the same shape:
{"error": {"code": "quota_exceeded", "message": "Not enough credits: 1500 requested, 236 remaining.", "details": {"requested": 1500, "remaining": 236}}} | HTTP | code | When |
|---|---|---|
| 401 | invalid_key | Missing, wrong or revoked key. |
| 403 | event_not_active | Event in draft or closed, or the API channel is disabled for it. |
| 404 | voucher_not_found | Unknown external_ref. |
| 409 | quota_exceeded | Not enough credits. details: requested, remaining. |
| 409 | code_conflict | The code is already used by another external_ref in this event. details: index, code, external_ref. |
| 409 | voucher_void | The voucher was voided and can't be updated. |
| 422 | validation_failed | Invalid JSON or fields. details: per-item field errors keyed by array index, e.g. {"1": {"profile": "unknown profile…"}}. |
| 429 | rate_limited | Over 60 requests per minute per key. details.retry_after in seconds. |
Rate limits
60 requests per minute per key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; a 429 also carries Retry-After. Batch your writes: one POST /vouchers takes up to 500 vouchers.
Idempotency & all-or-nothing
- Idempotent by
external_ref. Re-sending the same ref updates that voucher instead of creating a second one; credits are re-reserved for the difference only. Retrying a timed-out request is always safe. - All-or-nothing. If any item fails validation, a code conflicts, or the pool lacks credits for the whole request, nothing is created or changed.
- Quota. A voucher reserves the sum of its profile's meals (e.g. Delegate = 3 lunches = 3 credits). If credits run out, ask your KCC event manager for a top-up.
Codes, QR & badges
- KCC codes are
KCCV-+ 20 Crockford Base32 characters, random (~100 bits), never sequential. - The QR content is the bare code — no URL — so any scanner reads it and it stays small.
qr_png_urlserves a PNG while the event is active; render your own QR from the code if you prefer. - Linked codes are matched exactly as sent (case-sensitive) and are unique per event, not globally.
KCCV-: those are meal vouchers, not badges.Scanner integration (SD60 app)
Restaurant scanners — the /scan web app and the SD60 Android check-in app — use these endpoints. They're for KCC devices, not organisers. A valid scan redeems immediately with no confirm tap.
/scan/api/login{"restaurant_id": 1, "pin": "4821", "device_id": "sd60-filini-02"}{"token": "…"}Send the token as Authorization: Bearer <token> on every call below. Five wrong PINs lock the device for five minutes.
/scan/api/shift{"meal_type_name": "Lunch"} Picks the service once per shift; every scan then uses that meal type.
/scan/api/redeem{
"code": "AHTS26-7F3K9Q",
"meal_type_name": "Lunch",
"mode": "redeem",
"event_id": 12
}{
"tone": "green",
"result": "served",
"headline": "Served",
"line": "Lunch · Africa Health Tech Summit",
"holder": "Jane Doe",
"left": "2 lunches left",
"redemption_id": 90211
}mode is redeem or check (balance only, no credit used, returns balance). event_id is only needed when the same code exists in two events today: the first call then returns events for staff to pick, and the scanner repeats the call with the chosen event_id.
| tone | result | Credit used |
|---|---|---|
| green | served | Yes |
| amber | just_served, daily_limit, wrong_restaurant, outside_hours | No |
| red | invalid, void, used_up, no_entitlement, event_closed | No |
/scan/api/reverse{"redemption_id": 90211, "reason": "Wrong person"} Staff can undo their own redemption within 5 minutes (reasons: wrong person, scanned by mistake, other). After that only a KCC event manager can reverse it.
Data protection
Under Rwanda Law No. 058/2021, the only personal data the API accepts is holder_name, and it is optional. No email, phone or photo is accepted in v1. You are the data provider; KCC processes it only to serve meals and report usage.
holder_name and external_ref are purged 90 days after the event closes. Redemption counts are kept for reporting.
Questions? Email events@kcc.rw.
