POST /referrer
curl --request POST \
--url https://api.promostack.app/referrer \
--header 'Content-Type: application/json' \
--data '
{
"uid": "<string>",
"metadata": {}
}
'import requests
url = "https://api.promostack.app/referrer"
payload = {
"uid": "<string>",
"metadata": {}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({uid: '<string>', metadata: {}})
};
fetch('https://api.promostack.app/referrer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.promostack.app/referrer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'uid' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.promostack.app/referrer"
payload := strings.NewReader("{\n \"uid\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.promostack.app/referrer")
.header("Content-Type", "application/json")
.body("{\n \"uid\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.promostack.app/referrer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"uid\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"error": {
"code": "VALIDATION_ERROR",
"message": "Missing required field: uid"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}
Referrer Endpoints
POST /referrer
Get or create a referrer and fetch their progress
POST
/
referrer
POST /referrer
curl --request POST \
--url https://api.promostack.app/referrer \
--header 'Content-Type: application/json' \
--data '
{
"uid": "<string>",
"metadata": {}
}
'import requests
url = "https://api.promostack.app/referrer"
payload = {
"uid": "<string>",
"metadata": {}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({uid: '<string>', metadata: {}})
};
fetch('https://api.promostack.app/referrer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.promostack.app/referrer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'uid' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.promostack.app/referrer"
payload := strings.NewReader("{\n \"uid\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.promostack.app/referrer")
.header("Content-Type", "application/json")
.body("{\n \"uid\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.promostack.app/referrer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"uid\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"error": {
"code": "VALIDATION_ERROR",
"message": "Missing required field: uid"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}
Get or Create Referrer
This unified endpoint performs two actions:- Get or Create: Checks if a referrer exists for the given
uid. If not, creates a new one. - Fetch Progress: Returns the referrer’s current stats, rewards earned, and progress toward the next reward.
Request
string
required
Unique identifier for the user in your app (e.g., user ID, RevenueCat app_user_id)
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
string
Unique identifier for the referrer
string
Full URL to the referral landing page
string
Unique slug for the referrer (part of the URL)
string
The metacode that referees will enter in the app (same as referrer_slug)
string
Referrer status:
active, paused, or endedobject
object
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)
}
suspend fun getReferrer(userId: String): ReferrerResponse {
val client = OkHttpClient()
val json = JSONObject().put("uid", userId)
val request = Request.Builder()
.url("https://api.promostack.app/referrer")
.post(json.toString().toRequestBody("application/json".toMediaType()))
.addHeader("x-api-key", apiKey)
.build()
val response = client.newCall(request).execute()
return Gson().fromJson(response.body?.string(), ReferrerResponse::class.java)
}
Error Responses
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Missing required field: uid"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}
⌘I