Getting Started
Welcome to the Raba7ni Developer API! Follow these steps to integrate our loyalty platform into your systems.
Create Your Application
Log in to your partner dashboard and create a new developer application to get your App ID and Secret.
Generate API Keys
Create API keys with the appropriate scopes for your integration. Choose only the permissions your application needs.
Make Your First Request
Use your App ID and API Key to authenticate and start making requests to our endpoints.
Quick Example
Here's a simple cURL request to validate a member:
curl -X POST "https://app.raba7ni.com/api/v1/developer/validate-member" \
-H "X-App-Id: app_your_app_id" \
-H "X-Api-Key: dev_your_api_key" \
-H "Content-Type: application/json" \
-d '{"card_id": 5, "phone_number": "+21612345678"}'Authentication
The Developer API uses header-based authentication with your App ID and API Key.
Security Best Practices
Never expose your API keys in client-side code. Always make API calls from your server.
Request Headers
Include these headers in every API request:
X-App-Id: app_your_application_id
X-Api-Key: dev_your_api_key
Content-Type: application/jsonResponse Format
All API responses follow this consistent JSON structure:
{
"success": true,
"data": {
// Response data here
},
"message": "Optional status message"
}API Endpoints
All endpoints are available at: /api/v1/developer/
Available Scopes
member_read
Read access to members
member_write
Create and update members
card_read
Read cards and rewards
claim_write
Manage claim requests
referral_read
Read referral data
referral_write
Apply referral codes
Member Endpoints
/api/v1/developer/validate-member
Check if a phone number is a member of a specific loyalty card.
Request Body
{
"card_id": 5,
"phone_number": "+21612345678",
"include_member_data": false
}
card_id (integer, required) - The loyalty card ID
phone_number (string, required) - Phone number to validate
include_member_data (boolean, optional) - Include full member details
Response
{
"success": true,
"data": {
"is_member": true,
"validated_at": "2025-01-15T10:30:00Z"
}
}/api/v1/developer/member-details
Get detailed information about a member for a specific card including points balance.
Request Body
{
"card_id": 5,
"phone_number": "+21612345678"
}Response
{
"success": true,
"data": {
"member": {
"id": 123,
"name": "Ahmed Ben Ali",
"email": "ahmed@example.com",
"phone": "+21612345678",
"points_balance": 450,
"created_at": "2024-06-15T10:30:00Z"
}
}
}/api/v1/developer/members/request-otp
Send a verification code to an email for new member registration. Required before creating new members.
OTP Flow
If email already exists as a member, returns member_exists: true and no OTP is sent.
Request Body
{
"email": "newuser@example.com",
"card_id": 5
}Response
{
"success": true,
"data": {
"expires_at": "2025-01-15T10:40:00Z",
"expires_in_minutes": 10
},
"message": "Verification code sent to email."
}/api/v1/developer/find-or-create-member
Find a member by email/phone or create a new account. OTP verification required for new members. Optionally create an order and award points.
Phone Handling
New members: phone_number + verification_code required.
Existing members: phone_number is optional. If provided and member has no phone, it will be updated.
Phone Conflict
If phone exists with different email, returns error with masked email (e.g., a***@example.com).
Request Body
{
"card_id": 5,
"name": "Ahmed Ben Ali",
"email": "ahmed@example.com",
"phone_number": "+21612345678",
"verification_code": "123456",
"create_order": true,
"order": {
"award_points": true,
"total_amount": 50.00,
"items": [
{"name": "Coffee", "amount": 15.00}
]
}
}
card_id (integer, required)
name (string, required)
email (string, required)
phone_number (string, required for new members, optional for existing)
verification_code (string, required for new members)
create_order (boolean, optional)
order (object, if create_order is true)
Response
{
"success": true,
"data": {
"member": {
"id": 123,
"name": "Ahmed Ben Ali",
"email": "ahmed@example.com",
"phone": "+21612345678"
},
"is_new": true,
"matched_by": null,
"phone_updated": false,
"card_id": 5,
"order": {
"id": 456,
"total_amount": 50.00,
"points_awarded": true
},
"transaction": {
"id": 789,
"points": 50
}
}
}Card Endpoints
/api/v1/developer/cards
List all loyalty cards accessible to this API key.
Response
{
"success": true,
"data": {
"cards": [
{
"id": 5,
"unique_identifier": "abc123",
"name": "Coffee Rewards",
"head": "Earn points with every purchase",
"is_active": true,
"points_per_currency": 1,
"currency_unit_amount": 1.00,
"club_id": 10
}
],
"total": 1
}
}/api/v1/developer/cards/{card_id}
Get detailed information about a specific loyalty card.
URL Parameter: card_id (integer, required) - The card ID
/api/v1/developer/cards/{card_id}/rewards
Get all active rewards available for a specific card.
Response
{
"success": true,
"data": {
"card_id": 5,
"rewards": [
{
"id": 1,
"name": "Free Coffee",
"title": {"en": "Free Coffee"},
"points": 100,
"reward_type": "discount",
"is_active": true
}
],
"total": 1
}
}Claim Request Endpoints
/api/v1/developer/claim-requests?card_id={card_id}&status={status}
Get all claim requests for a card, optionally filtered by status.
Query Parameters:
card_id (integer, required) - The card ID
status (string, optional) - Filter: pending, approved, rejected, expired
/api/v1/developer/claim-requests/request-otp
Request a verification code for claiming a reward. OTP is sent to member's email.
Request Body
{
"member_email": "ahmed@example.com",
"card_id": 5,
"reward_id": 1
}
member_email (string, required)
card_id (integer, required)
reward_id (integer, optional)
Response
{
"success": true,
"data": {
"expires_at": "2025-01-15T10:40:00Z",
"expires_in_minutes": 10
},
"message": "Verification code sent to member email."
}/api/v1/developer/claim-requests
Create a new reward claim request. OTP verification required.
Request Body
{
"member_email": "ahmed@example.com",
"card_id": 5,
"reward_id": 1,
"verification_code": "123456",
"member_note": "Pickup at downtown branch"
}Response
{
"success": true,
"data": {
"claim_request": {
"id": 100,
"status": "pending",
"created_at": "2025-01-15T10:30:00Z"
}
}
}/api/v1/developer/claim-requests/{request_id}
Get details of a specific claim request.
/api/v1/developer/claim-requests/{request_id}/approve
Approve a pending claim request and process the reward.
Request Body
{
"staff_note": "Approved via API"
}/api/v1/developer/claim-requests/{request_id}/reject
Reject a pending claim request.
Request Body
{
"staff_note": "Insufficient points balance"
}Referral Endpoints
/api/v1/developer/cards/{card_id}/referral-stats
Get referral statistics for a card including total, successful, and pending referrals.
/api/v1/developer/cards/{card_id}/referrers
Get list of top referrers for a card.
/api/v1/developer/cards/{card_id}/referrers/{member_id}/referrals
Get all referrals made by a specific member.
/api/v1/developer/referrals/validate-code
Check if a referral code is valid for a specific card.
Request Body
{
"referral_code": "AHMED2024",
"card_id": 5
}Response
{
"success": true,
"data": {
"is_valid": true,
"referrer": {
"id": 123,
"name": "Ahmed Ben Ali"
}
}
}/api/v1/developer/referrals/apply
Apply a referral code to a new member and award bonus points to both parties.
Request Body
{
"referral_code": "AHMED2024",
"card_id": 5,
"referee_email": "newuser@example.com"
}
referral_code (string, required)
card_id (integer, required)
referee_email (string, required) - New member's email
Response
{
"success": true,
"message": "Referral applied successfully",
"data": {
"referral": {
"referrer_bonus": 50,
"referee_bonus": 25
}
}
}Try It Yourself
Use our interactive API tester to experiment with all these endpoints in real-time.
Open API Tester