API v1RESTful · JSON · Webhooks

RibiRewards
API Documentation

Integrate gifting infrastructure into your product. RESTful API with SDKs for JavaScript, Python, and more. Sandbox environment included.

Quick Start →Request API Access

REST

API Type

JSON

Format

< 200ms

Avg Latency

99.9%

Uptime SLA

Quick Start

Send your first reward in 5 minutes

Install the SDK, initialise with your API key, and send your first reward. Everything runs against our sandbox by default.

send-reward.js

import RibiRewards from '@ribi/sdk';

const ribi = new RibiRewards({
  apiKey: process.env.RIBI_API_KEY
});

// Send a choice card reward
const reward = await ribi.rewards.send({
  recipient: {
    name: 'Amara Okafor',
    email: 'amara@company.ng',
    country: 'NG'
  },
  reward_type: 'choice_card',
  amount: 25000,
  currency: 'NGN',
  categories: ['food', 'wellness'],
  expiry_days: 60
});

console.log(reward.id, reward.status);
// → rwd_01HX... "sent"

API Reference

Endpoints

POST/v1/rewards/sendSend a reward to one or more recipientsCore

GET/v1/rewards/{id}Retrieve reward details and statusCore

GET/v1/rewardsList all rewards with filtering & paginationCore

POST/v1/campaignsCreate a reward campaign with budget rulesCampaigns

GET/v1/campaigns/{id}/statsGet campaign redemption statsCampaigns

GET/v1/catalog/choice-cardsBrowse available choice card brandsCatalog

GET/v1/catalog/experiencesList experience reward options by cityCatalog

POST/v1/recipients/bulkUpload recipients CSV for bulk sendingRecipients

GET/v1/webhooksList configured webhook endpointsWebhooks

POST/v1/webhooksRegister a new webhook endpointWebhooks

Authentication

API Keys

All API requests must include your secret API key in the Authorization header.

Authorization: Bearer sk_live_...your_api_key...

# Test keys start with sk_test_
Authorization: Bearer sk_test_...your_test_key...

Send your first reward in 5 minutes

Install the SDK, initialise with your API key, and send your first reward. Everything runs against our sandbox by default.

send-reward.js

import RibiRewards from '@ribi/sdk';

const ribi = new RibiRewards({
  apiKey: process.env.RIBI_API_KEY
});

// Send a choice card reward
const reward = await ribi.rewards.send({
  recipient: {
    name: 'Amara Okafor',
    email: 'amara@company.ng',
    country: 'NG'
  },
  reward_type: 'choice_card',
  amount: 25000,
  currency: 'NGN',
  categories: ['food', 'wellness'],
  expiry_days: 60
});

console.log(reward.id, reward.status);
// → rwd_01HX... "sent"

Endpoints

POST/v1/rewards/sendSend a reward to one or more recipientsCore

GET/v1/rewards/{id}Retrieve reward details and statusCore

GET/v1/rewardsList all rewards with filtering & paginationCore

POST/v1/campaignsCreate a reward campaign with budget rulesCampaigns

GET/v1/campaigns/{id}/statsGet campaign redemption statsCampaigns

GET/v1/catalog/choice-cardsBrowse available choice card brandsCatalog

GET/v1/catalog/experiencesList experience reward options by cityCatalog

POST/v1/recipients/bulkUpload recipients CSV for bulk sendingRecipients

GET/v1/webhooksList configured webhook endpointsWebhooks

POST/v1/webhooksRegister a new webhook endpointWebhooks

RibiRewardsAPI Documentation

Send your first reward in 5 minutes

Endpoints

API Keys

RibiRewardsAPI Documentation

Send your first reward in 5 minutes

Endpoints

API Keys

RibiRewards
API Documentation

RibiRewards
API Documentation