Skip to main content
POST
/
referrer
POST /referrer
curl --request POST \
  --url https://api.promostack.app/referrer \
  --header 'Content-Type: application/json' \
  --data '
{
  "uid": "<string>",
  "metadata": {}
}
'
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: uid"
  }
}

​
Get or Create Referrer

This unified endpoint performs two actions:
  1. Get or Create: Checks if a referrer exists for the given uid. If not, creates a new one.
  2. Fetch Progress: Returns the referrer’s current stats, rewards earned, and progress toward the next reward.
Use this endpoint when a user opens the referral section of your app.

​
Request

​
uid
string
required
Unique identifier for the user in your app (e.g., user ID, RevenueCat app_user_id)
​
metadata
object
Optional metadata about the referrer (e.g., display name, avatar URL). Only used when creating a new referrer.

​
Example Request

curl -X POST https://api.promostack.app/referrer \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user_123",
    "metadata": {
      "name": "John Doe"
    }
  }'

​
Response

​
referrer_id
string
Unique identifier for the referrer
​
referral_link
string
Full URL to the referral landing page
​
referrer_slug
string
Unique slug for the referrer (part of the URL)
​
metacode
string
The metacode that referees will enter in the app (same as referrer_slug)
​
status
string
Referrer status: active, paused, or ended
​
stats
object
General statistics
​
progress
object
Platform-specific progress details

​
Example Response

{
  "referrer_id": "550e8400-e29b-41d4-a716-446655440000",
  "referral_link": "https://promostack.app/r/abc123",
  "referrer_slug": "abc123",
  "metacode": "abc123",
  "status": "active",
  "stats": {
    "referrals_count": 3,
    "rewards_earned": 0
  },
  "progress": {
    "ios": {
      "current": 3,
      "threshold": 5,
      "next_reward_at": 5,
      "percentage": 60
    },
    "android": {
      "current": 0,
      "threshold": 5,
      "next_reward_at": 5,
      "percentage": 0
    }
  }
}

​
Usage in Mobile App

struct ReferrerResponse: Codable {
    let referrer_id: String
    let referral_link: String
    let metacode: String
    let stats: Stats
    let progress: Progress
}

func getReferrer(userId: String) async throws -> ReferrerResponse {
    let url = URL(string: "https://api.promostack.app/referrer")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    
    let body = ["uid": userId]
    request.httpBody = try JSONEncoder().encode(body)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONDecoder().decode(ReferrerResponse.self, from: data)
}

​
Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: uid"
  }
}