Developers
Tuma zawadi moja kwa moja kutoka kwenye mfumo wako wa HR.
The GiftHub API lets an HR, payroll or CRM system send gift cards, keep the employee directory in step and hear when a gift is redeemed. This page is the overview; the reference for your account lives in the business portal.
curl https://gifthub.co.ke/api/v1/me \
-H "Authorization: Bearer $GIFTHUB_API_KEY"01Authentication
An organisation admin creates keys in the business portal. Send the key in the Authorization header of every request, over HTTPS.
A key starts with zl_live_ and is displayed a single time when created. We store only a hash, so a lost key is replaced, not recovered.
Load the key from an environment variable or a secret manager. Never put it in a mobile app, a web page or source control, and revoke it in the portal if it leaks.
Sends made by API follow your own rules
02Endpoints
JSON in, JSON out. Amounts are in cents of a shilling (KES 3,000 is 300000). Phone numbers are Kenyan mobile numbers in any common format.
GET/api/v1/me
The organisation behind the key. A good first call to check that a key works.
GET/api/v1/brands
Brands you can send, with the amounts each one accepts.
GET/api/v1/employees
Your employee directory.
POST/api/v1/employees
Add or update employees. Matched on your external_id, then phone, then email.
POST/api/v1/sends
Create a send to one or many recipients. Requires an Idempotency-Key header.
GET/api/v1/sends/:id
Status of a send and of each gift in it: delivered, opened, redeemed.
GET/api/v1/analytics
Totals for a period or one send: sent, delivered, opened, redeemed, by brand and by month.
Each item names a recipient, an amount and either a brand or choice for a Zawadi Choice card. Every row is validated before anything is created: if one fails, the whole request is refused with the row number, and nothing is sent.
curl -X POST https://gifthub.co.ke/api/v1/sends \
-H "Authorization: Bearer $GIFTHUB_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: awards-2026-12-batch-01" \
-d '{
"name": "Long-service awards, December",
"items": [
{
"recipient_name": "Wanjiru Kamau",
"recipient_phone": "0712345678",
"merchant": "choice",
"amount_cents": 300000,
"message": "Five years. Thank you for all of it."
},
{
"recipient_name": "Otieno Mboya",
"recipient_email": "otieno@example.invalid",
"merchant": "soko-fresh",
"amount_cents": 300000
}
]
}'Use a value that identifies the send in your system. Repeating a request with the same key returns the original send instead of creating a second one, so a timeout is always safe to retry.
By sending a recipient's contact details you confirm you are entitled to share them for this purpose, as set out in our terms.
Send only what a reward needs: a name, a phone number or email, and the dates your automated rules use. Dates are YYYY-MM-DD.
curl -X POST https://gifthub.co.ke/api/v1/employees \
-H "Authorization: Bearer $GIFTHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employees": [
{
"external_id": "EMP-0142",
"full_name": "Amina Hassan",
"phone": "0722000111",
"department": "Finance",
"date_of_birth": "1994-03-21",
"start_date": "2021-09-01"
}
]
}'The examples use made-up people. Field-by-field reference, error formats and limits are in the portal under Developers.
03Webhooks
Register an HTTPS endpoint in the portal and choose the events you want. Each delivery is a JSON POST signed with your endpoint's secret.
voucher.issued
A gift was created and queued for delivery to its recipient.
voucher.redeemed
A gift was used in store. Includes whether it is now fully redeemed. Sent on each partial use.
batch.sent
Every gift in a send has been issued.
POST /your/webhook/path
Content-Type: application/json
X-GiftHub-Signature: sha256=<hex hmac of the raw body>
{
"event": "voucher.redeemed",
"data": {
"voucher_id": "0b9c1f0e-6a54-4f0e-9d0b-2f6f6d1c9a11",
"batch_id": "5d2a7c46-1d0f-4a39-8a3e-7c1b6c0e44d2",
"fully_redeemed": false
},
"sent_at": "2026-12-04T09:41:12.000Z"
}The header X-GiftHub-Signature is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your endpoint secret. Compute it yourself and compare in constant time before trusting the payload.
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";
const app = express();
const secret = process.env.GIFTHUB_WEBHOOK_SECRET;
// Keep the raw bytes: the signature covers the body exactly as it was sent.
app.post("/webhooks/gifthub", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("X-GiftHub-Signature") ?? "";
const expected = "sha256=" + createHmac("sha256", secret).update(req.body).digest("hex");
const a = Buffer.from(header);
const b = Buffer.from(expected);
if (a.length !== b.length || !timingSafeEqual(a, b)) {
return res.status(401).end();
}
const { event, data } = JSON.parse(req.body.toString("utf8"));
if (event === "voucher.redeemed") {
// Mark the reward as used in your own system.
}
res.status(200).end(); // Reply quickly; do slow work afterwards.
});A delivery that gets no 2xx response within a few seconds is retried a limited number of times. Events can arrive more than once or out of order, so make your handler idempotent.
Webhook payloads carry identifiers and status, never the voucher code, and never what an individual bought.
Create a business account, then generate a key under Developers in the portal. Need help planning an integration? Talk to us.