Users API

Query user referral data and manage referrers.

The Users API lets you query referral statistics, view rewards, and manage user permissions.

GET/v1/users/:userId/stats

Get referral statistics for a user.

Parameters

Name	Type	Required	Description
userId	string	Required	Your user identifier
campaignId	string	Optional	Filter by campaign

Response

{
  "userId": "user_123",
  "referralCount": 15,
  "conversionCount": 8,
  "conversionRate": 0.53,
  "totalRewardsEarned": 80,
  "pendingRewards": 10,
  "topReferralSource": "whatsapp",
  "byStatus": {
    "clicked": 15,
    "installed": 12,
    "signedUp": 10,
    "converted": 8
  }
}

GET/v1/users/:userId/rewards

Get all rewards earned by a user.

Parameters

Name	Type	Required	Description
userId	string	Required	Your user identifier
status	string	Optional	Filter: pending, fulfilled, expired
limit	number	Optional	Max results (default 20)

Response

{
  "data": [
    {
      "id": "reward_xxxxx",
      "type": "referrer",
      "amount": 10,
      "currency": "USD",
      "status": "fulfilled",
      "referredUserId": "user_456",
      "campaignId": "camp_xxxxx",
      "createdAt": "2024-01-15T10:30:00Z",
      "fulfilledAt": "2024-01-15T10:31:00Z"
    }
  ],
  "total": 8,
  "totalAmount": 80
}

GET/v1/users/:userId/referrals

Get users referred by this user.

Parameters

Name	Type	Required	Description
userId	string	Required	The referrer's user ID
status	string	Optional	Filter by referral status

Response

{
  "data": [
    {
      "referredUserId": "user_456",
      "status": "converted",
      "clickedAt": "2024-01-14T10:00:00Z",
      "signedUpAt": "2024-01-14T10:05:00Z",
      "convertedAt": "2024-01-15T10:30:00Z",
      "rewardIssued": true
    }
  ],
  "total": 8
}

POST/v1/users/:userId/disable

Disable a user as a referrer. Their links will no longer track referrals.

Parameters

Name	Type	Required	Description
userId	string	Required	User to disable
reason	string	Optional	Reason for disabling

Response

{
  "userId": "user_123",
  "disabled": true,
  "disabledAt": "2024-01-15T10:30:00Z"
}