Skip to main content

Get User Referral Code API

Overview​

Retrieve user referral code information by user ID or referral code. This API allows you to fetch referral code details including the code itself, associated program, user information, and referral limit status. You can query either by user ID to get their referral code, or by referral code to get the associated user information.

API Details​

Endpoint​

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

Headers​

authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmYjhmMDkyMTBlMGY0NmI3YjQyNjJkNzdmNWI2YzI3MyIsInJvbGVzIjpbIlJPTEVfQ1VTVE9NRVIiXSwiZXhwIjoxNzYwMTU2MjgzfQ.iHC4alnoYacGsKM0GNPKBvlv9NFEzGU8xLhZ1Ysbx-g
requestid: 5bb30135-1815-41d5-827f-baed3daba4ae
companyid: 59388167894b4d10a04fe5da3b8a2104

Query Parameters​

Required Parameters​

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

Search Parameters (Choose One)​

  • user_id (String): User identifier to get their referral code
    • Example: "fb8f09210e0f46b7b4262d77f5b6c273"
    • Description: Find referral code by user ID
  • referral_code (String): Referral code to get associated user information
    • Example: "C273551489XA"
    • Description: Find user information by referral code

Optional Parameters​

  • currency_id (String): Currency identifier for context
    • Example: "1f1519903ed240578f071aa45cb479f2"
    • Description: Used for program-specific filtering
  • referral_program_id (String): Specific referral program identifier
    • Example: "3a62eae282ea4e04bbe27e2dddbb1e5c"
    • Description: Filter by specific referral program

Validation Rules​

  • Either-Or Logic: Must provide either user_id OR referral_code, not both
  • Company Scoped: All queries are scoped to the company_id in headers
  • Program Filtering: Optional referral_program_id provides additional context

Response​

Success Response​

{
    "success": 1,
    "error": [],
    "data": {
        "referral_user": {
            "id": "a0507a9d8ff441f59df3853cfa920424",
            "user_type": 2,
            "user_id": "fb8f09210e0f46b7b4262d77f5b6c273",
            "referral_code": "C273551489XA",
            "referral_program_id": null,
            "max_referral_limit_reach": false
        }
    }
}

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_user (object): Referral user information

Referral User Object Fields​

  • id (string): Referral code record unique identifier
    • Example: "a0507a9d8ff441f59df3853cfa920424"
  • user_type (integer): Type of user
    • 2 = Customer
    • 3 = Merchant
    • 5 = Agent
  • user_id (string): User identifier
    • Example: "fb8f09210e0f46b7b4262d77f5b6c273"
  • referral_code (string): The referral code
    • Example: "C273551489XA"
    • Description: The actual referral code that can be shared
  • referral_program_id (string|null): Associated referral program ID
    • Example: "3a62eae282ea4e04bbe27e2dddbb1e5c" or null
    • Description: Links to specific referral program, null if not associated
  • max_referral_limit_reach (boolean): Referral limit status
    • false = Can still accept more referrals
    • true = Maximum referral limit reached

Error Responses​

Bad Request​

{
    "success": 0,
    "error": ["BAD_REQUEST"],
    "data": {}
}

Referral Code Not Found​

{
    "success": 0,
    "error": ["REWARD_PROMOTION_USER_REFERRAL_CODE_NOT_FOUND"],
    "data": {}
}

Invalid Parameters​

{
    "success": 0,
    "error": ["INVALID_REQUEST_PARAMETERS"],
    "data": {}
}

Example Usage​

Get Referral Code by User ID​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/user_referral_code?user_id=fb8f09210e0f46b7b4262d77f5b6c273&currency_id=1f1519903ed240578f071aa45cb479f2&referral_program_id=3a62eae282ea4e04bbe27e2dddbb1e5c' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'companyid: YOUR_COMPANY_ID'

Get User Info by Referral Code​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/user_referral_code?referral_code=C273551489XA' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'companyid: YOUR_COMPANY_ID'

Simple User ID Lookup​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/user_referral_code?user_id=fb8f09210e0f46b7b4262d77f5b6c273' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'companyid: YOUR_COMPANY_ID'

Error Messages​

  • BAD_REQUEST: Invalid or missing required parameters
  • REWARD_PROMOTION_USER_REFERRAL_CODE_NOT_FOUND: No referral code found for given criteria
  • INVALID_REQUEST_PARAMETERS: Parameter validation failed

Notes​

  • Either-Or Search: Must provide either user_id OR referral_code, not both
  • Company Scoped: All queries automatically scoped to company_id from headers
  • Program Association: referral_program_id can be null if code not linked to specific program