Skip to main content

Get All Referral Programs API

Overview​

Retrieve all referral programs with optional filtering and pagination support. Referral programs define the reward structure and conditions for users who refer others to the platform, including reward amounts, limits, and eligibility criteria.

API Details​

Endpoint​

GET https://api.gafapay.com:8443/gafapay/v3/reward_promotion/referral_program

Headers​

authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmYjhmMDkyMTBlMGY0NmI3YjQyNjJkNzdmNWI2YzI3MyIsInJvbGVzIjpbIlJPTEVfQ1VTVE9NRVIiXSwiZXhwIjoxNzYwMTQ4NjAyfQ.1vBPSBGvYI7mTe7JJqYE7C5r2uRkhkS_mI2sW1rumrs
companyid: 59388167894b4d10a04fe5da3b8a2104
requestid: 5bb30135-1815-41d5-827f-baed3daba4ae

Query Parameters​

Required Parameters​

  • company_id (String): Company identifier (passed in header)

Optional Parameters​

  • user_type (Integer): Type of user for referral program
    • 2 = Customer
    • 3 = Merchant
    • 5 = Agent
  • currency_id (String): Currency identifier for reward amounts
  • referral_for (Integer): Target user type for referrals
    • 2 = Customer
    • 3 = Merchant
    • 5 = Agent
  • status (Integer): Program status filter
    • 1 = Inactive
    • 2 = Active
  • referfrom_rewards_type (Integer): Referrer reward type
  • referto_rewards_type (Integer): Referee reward type
  • skip (Integer): Number of records to skip (pagination)
    • Default: 0
    • Example: 0, 10, 20
  • limit (Integer): Maximum number of records to return (pagination)
    • Default: 10
    • Example: 10, 25, 50
  • search_keyword (String): Search data using any keyword
  • sorting (String): Sorting criteria (JSON format)
    • Example: {"created_date": "DESC"}
  • start_date (Long): Start date filter (epoch timestamp)
  • end_date (Long): End date filter (epoch timestamp)
  • is_active (Boolean): Active status filter

Response​

{
    "success": 1,
    "error": [],
    "data": {
        "referral_programs": [
            {
                "is_active": true,
                "created_by": "640b793d04e2428dbf19ab10399f4edb",
                "created_date": 1704795271,
                "updated_by": "640b793d04e2428dbf19ab10399f4edb",
                "updated_date": 1733871272,
                "id": "3a62eae282ea4e04bbe27e2dddbb1e5c",
                "referral_program_title": "Customer Referral",
                "referfrom_rewards_type": 1,
                "referto_rewards_type": 1,
                "referral_for": 2,
                "expiry_date": 1755302400,
                "min_referrals": 1,
                "max_referrals": 5,
                "referral_reward_users": 3,
                "referral_condition": {
                    "refer_type": 1,
                    "refer": {
                        "referfrom_value": "100",
                        "referfrom_value_type": 2,
                        "referto_value": "50",
                        "referto_value_type": 2
                    },
                    "transaction": {}
                },
                "status": 2,
                "message": "",
                "currency_id": "1f1519903ed240578f071aa45cb479f2"
            }
        ]
    }
}

Response Fields​

  • success (integer): Response status indicator
    • 1 = Success
    • 0 = Failure
  • error (array): Array of error messages (empty on success)
  • data (object): Response data object
    • referral_programs (array): Array of referral program objects

Referral Program Object Fields​

  • id (string): Referral program unique identifier
  • referral_program_title (string): Display name of the referral program
  • referfrom_rewards_type (integer): Type of reward for referrer
    • 1 = Points
    • 2 = Cash
    • 3 = Voucher
  • referto_rewards_type (integer): Type of reward for referee
    • 1 = Points
    • 2 = Cash
    • 3 = Voucher
  • referral_for (integer): Target user type for referrals
    • 2 = Customer
    • 3 = Merchant
    • 5 = Agent
  • expiry_date (long): Program expiry timestamp (epoch)
  • min_referrals (integer): Minimum number of referrals required
  • max_referrals (integer): Maximum number of referrals allowed
  • referral_reward_users (integer): Number of users who can receive rewards
  • referral_condition (object): Detailed referral conditions and rewards
    • refer_type (integer): Type of referral condition
    • refer (object): Referral reward details
      • referfrom_value (string): Reward amount for referrer
      • referfrom_value_type (integer): Value type for referrer reward
      • referto_value (string): Reward amount for referee
      • referto_value_type (integer): Value type for referee reward
    • transaction (object): Transaction-based conditions (if applicable)
  • status (integer): Program status
    • 1 = Inactive
    • 2 = Active
  • message (string): Additional program message or description
  • currency_id (string): Currency identifier for reward amounts
  • is_active (boolean): Program active status
  • created_date (long): Creation timestamp (epoch)
  • created_by (string): ID of the user who created the program
  • updated_by (string|null): ID of the user who last updated the program
  • updated_date (long|null): Last update timestamp (epoch)

Example Usage​

Basic Request​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/referral_program?user_type=2&currency_id=1f1519903ed240578f071aa45cb479f2' \
--header 'authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmYjhmMDkyMTBlMGY0NmI3YjQyNjJkNzdmNWI2YzI3MyIsInJvbGVzIjpbIlJPTEVfQ1VTVE9NRVIiXSwiZXhwIjoxNzYwMTQ4NjAyfQ.1vBPSBGvYI7mTe7JJqYE7C5r2uRkhkS_mI2sW1rumrs' \
--header 'companyid: 59388167894b4d10a04fe5da3b8a2104' \
--header 'requestid: 5bb30135-1815-41d5-827f-baed3daba4ae'

Request with Status Filter​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/referral_program?user_type=2&status=2&currency_id=1f1519903ed240578f071aa45cb479f2' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID'
curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/referral_program?user_type=2&skip=0&limit=10&search_keyword=Customer' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID'

Referral Program Constants​

User Type Constants​

  • Customer = 2: Regular customer users
  • Merchant = 3: Merchant/business users
  • Agent = 5: Agent/representative users

Reward Type Constants​

  • Points = 1: Reward points that can be redeemed
  • Cash = 2: Direct cash rewards
  • Voucher = 3: Voucher or discount rewards

Program Status Constants​

  • Inactive = 1: Program is not currently active
  • Active = 2: Program is active and accepting referrals

Refer Type Constants​

  • Direct Referral = 1: Simple referral without additional conditions
  • Transaction Based = 2: Referral requires transaction completion
  • Conditional = 3: Referral with specific conditions

Value Type Constants​

  • Fixed Amount = 1: Fixed reward amount
  • Percentage = 2: Percentage-based reward
  • Points = 3: Points-based reward

Referral Condition Structure​

Basic Referral Condition​

{
    "refer_type": 1,
    "refer": {
        "referfrom_value": "100",
        "referfrom_value_type": 2,
        "referto_value": "50",
        "referto_value_type": 2
    },
    "transaction": {}
}

Transaction-Based Referral Condition​

{
    "refer_type": 2,
    "refer": {
        "referfrom_value": "50",
        "referfrom_value_type": 1,
        "referto_value": "25",
        "referto_value_type": 1
    },
    "transaction": {
        "min_amount": 100,
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "transaction_type": 1
    }
}

Notes​

  • Multi-Currency Support: Programs can be filtered by currency_id for different markets
  • User Type Specific: Programs are designed for specific user types (Customer, Merchant, Agent)
  • Flexible Rewards: Supports different reward types (Points, Cash, Voucher)
  • Conditional Rewards: Complex referral conditions with transaction requirements
  • Expiry Management: Programs have expiry dates for time-limited campaigns
  • Referral Limits: Min/max referral limits per user
  • Multi-Company: All operations are scoped to the company_id in headers
  • Pagination: Use skip and limit parameters for efficient data retrieval
  • Search: The search_keyword parameter searches program titles and descriptions
  • Status Filtering: Filter by program status for active/inactive programs