Codes API
Validate, allocate and redeem a campaign's voucher codes from any system: a chatbot, a website backend, a mobile app's server or a till. Every endpoint is a JSON POST, and the campaign's API key decides which campaign it acts on.
| Endpoint | What it does |
|---|---|
| POST /public/v1/codes/validate | Checks that a code exists in the campaign and can still be redeemed. |
| POST /public/v1/codes/allocate | Gives a code to someone. |
| POST /public/v1/codes/redeem | Uses up a pending or allocated code. |
https://your-voucherverse-domain
Authentication
Send the campaign's API key as a bearer token on every request:
Authorization: Bearer vvb_...
- In the dashboard, open Campaigns, your campaign, then API access and Generate key. There is one key per campaign.
- Copy it straight away. It is shown once; VoucherVerse keeps only a hash of it.
- Rotate key issues a new one. The old key stops working immediately, so update your systems straight after.
Keep the key on your server (webhook, backend, till software). Never put it in a website's JavaScript or a mobile app: anyone who has it can allocate and redeem this campaign's codes.
Other ways into VoucherVerse use different credentials:
| API | For | Credentials |
|---|---|---|
/public/infobip/* | Infobip Answers bots | Install VoucherVerse from Infobip Exchange. Infobip signs each call; the campaign API key goes in the block's key field. See below. |
/public/campaigns/{campaignId}/vouchers/{code}/redeem | Merchant tills and POS | A merchant user's key in X-API-Key. Works for any campaign of that merchant's company. |
/api/* | The VoucherVerse dashboard | A session token from signing in (JWT, 24 hours). Not meant for integrations. |
Code states
PENDING ──allocate──▶ ALLOCATED ──redeem──▶ REDEEMED │ ▲ └──────────────────redeem────────────────────┘ PENDING or ALLOCATED ──expire (dashboard)──▶ EXPIRED
PENDING codes were generated or imported and belong to nobody yet. ALLOCATED codes belong to a customer or to your recipient ID. Both can be redeemed, and redeeming a pending code records the participant. Pre-printed codes go straight from pending to redeemed.
Validate a code
Checks that a code exists in the campaign and can still be redeemed. Nothing changes.
| Field | Description | |
|---|---|---|
code | required | The code the person typed. Surrounding spaces and letter case are ignored. Max 64 characters. |
participant | required | Who is acting: a stable ID such as a phone number in international format, your user ID, or a till ID. Used for the rate limit and recorded on the code. Max 128 characters. |
curl -X POST https://your-voucherverse-domain/public/v1/codes/validate \
-H "Authorization: Bearer $VOUCHERVERSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code":"VVX7K2M9QP","participant":"27821234567"}'{
"ok": true,
"status": "VALID",
"code": "VVX7K2M9QP",
"message": "This code is valid.",
"prize": "",
"prizeDescription": "",
"prizeCode": ""
}- Validating does not reserve the code. Redeem checks everything again, so you can call redeem on its own.
Allocate a code
Gives a code to someone. Leave out code to get the next pending code (for example when a chatbot user asks for a voucher), or pass one to allocate that exact code.
| Field | Description | |
|---|---|---|
code | optional | Allocate this pending code (letter case is ignored). Omit to take the next pending code. |
customerEmail | one of | The customer's email, stored and matched in lower case. Finds or creates the customer in your company. An address that isn't a valid email is refused with 400. |
customerPhone | one of | The customer's phone number: digits with the country code first, e.g. 27821234567 (a leading + is optional). A local number starting with 0 is refused with 400. |
externalId | one of | Your own ID for the recipient, stored on the code. One line, at most 128 characters. |
curl -X POST https://your-voucherverse-domain/public/v1/codes/allocate \
-H "Authorization: Bearer $VOUCHERVERSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"customerEmail":"jane@example.com","customerPhone":"27821234567","externalId":"crm-10492"}'{
"ok": true,
"status": "ALLOCATED",
"code": "VVX7K2M9QP",
"value": 10,
"expiresAt": "2026-12-31T00:00:00Z",
"customerId": "6ab63866289f9e796e87f1de",
"externalId": "crm-10492",
"message": "Here is your code."
}- Give at least one of customerEmail, customerPhone or externalId.
- Taking the next code is atomic: two requests at the same moment never get the same code.
- Allocation works before the campaign starts, so codes can be sent ahead of launch.
Redeem a code
Uses up a pending or allocated code. Each code can be redeemed once.
| Field | Description | |
|---|---|---|
code | required | The code to redeem. Surrounding spaces and letter case are ignored. |
participant | required | Who is acting: a stable ID such as a phone number in international format, your user ID, or a till ID. Used for the rate limit and recorded on the code. Max 128 characters. |
curl -X POST https://your-voucherverse-domain/public/v1/codes/redeem \
-H "Authorization: Bearer $VOUCHERVERSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code":"VVX7K2M9QP","participant":"27821234567"}'{
"ok": true,
"status": "REDEEMED",
"code": "VVX7K2M9QP",
"message": "Thanks, your code has been redeemed. You won a free meal! Your prize code is MEAL-4KD9.",
"prize": "a free meal",
"prizeDescription": "Show this at the counter.",
"prizeCode": "MEAL-4KD9"
}- If two requests redeem the same code at the same moment, exactly one gets REDEEMED; the other gets ALREADY_REDEEMED.
- Prize draws: if the campaign runs one, a redemption may win a prize. prize, prizeDescription and prizeCode say what (prizeCode is a code from another campaign, when the prize comes with one), and message adds "You won …!". The status is still REDEEMED. Every response carries these fields; they are empty strings when nothing was won.
Statuses and errors
Business outcomes, including refusals, come back as 200 with ok and a status to branch on. message is a suggested reply for the person, which you can show as-is or replace.
| status | ok | From | Meaning |
|---|---|---|---|
VALID | true | validate | The code exists and can be redeemed. |
ALLOCATED | true | allocate | The code now belongs to the recipient; it is in code. |
REDEEMED | true | redeem | The code was used up just now. |
NOT_FOUND | false | all | No such code in this campaign. |
ALREADY_ALLOCATED | false | allocate | That code already belongs to someone. |
ALREADY_REDEEMED | false | all | The code was redeemed before. |
EXPIRED | false | all | The code was expired. |
NO_CODES_LEFT | false | allocate | No pending codes left. Generate or import more in the dashboard. |
CAMPAIGN_CLOSED | false | all | The campaign is inactive or has ended (validate and redeem also refuse before it starts), or the company's VoucherVerse plan is unpaid or has ended. |
RATE_LIMITED | false | validate, redeem | 10 rejected codes from this participant in the last hour. Ask them to try later. |
Errors use other HTTP codes, with the same JSON shape:
| HTTP | status | When |
|---|---|---|
| 400 | BAD_REQUEST | Invalid JSON; missing code or participant (validate, redeem); no recipient (allocate). |
| 401 | INVALID_KEY | The API key is missing, wrong or rotated. The response carries WWW-Authenticate: Bearer. |
| 500 | ERROR | Something went wrong on our side. Retry with backoff; a redeem that failed did not use up the code. |
Limits and rules
- One redemption per code. Redeeming is atomic.
- Rate limit. After 10 rejected codes (not found, already redeemed, expired) from one participant in an hour, validate and redeem answer
RATE_LIMITED. This stops code guessing. Successful calls don't count. - Matching.
" vvx7k2m9qp "findsVVX7K2M9QP. The response'scodeis the code as stored. - Campaign dates. Validate and redeem work only while the campaign is active and within its dates. Allocate also works before it starts.
- Timeouts. Allow 10 seconds. Calls normally take well under a second.
Example: a chatbot
A promo where people type a code from the packaging into WhatsApp. Your bot's webhook calls redeem and answers with the result:
// Express-style webhook in your chatbot backend
app.post("/bot/code", async (req, res) => {
const { text, from } = req.body; // what the user typed, their phone number
const r = await fetch("https://your-voucherverse-domain/public/v1/codes/redeem", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.VOUCHERVERSE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ code: text, participant: from }),
}).then((x) => x.json());
if (r.ok) return res.json({ reply: "Thanks, your code is redeemed!" });
return res.json({ reply: r.message }); // not found, already used, try later...
});To hand out codes instead (“send me a voucher”), call allocate with the user's phone number and reply with the returned code.
Try it
Sends a real request from your browser. Validate is read-only; allocate and redeem change real codes, so use a test campaign.
Infobip without code
Bots built in Infobip Answers don't need any of the above. Install VoucherVerse from Infobip Exchange and add the validateCode and redeemCode blocks. Put the campaign API key in each block's key field, and map code and participant to bot attributes. The blocks return the same fields and statuses as this API. Infobip signs every call, so they use their own endpoints (/public/infobip/*) rather than this API.