Get referral programs
GET
/v1/referral/programs
What this endpoint does
INFO
communityId. The community API key supplies community scope and must include getUserData.Quick start
Authentication and permission
Authorization: Bearer <COMMUNITY_API_KEY>. Keep it server-side. Missing, invalid, or expired keys return 401; a valid key without getUserData returns 403.Query parameter
| Field | Required | Meaning |
|---|---|---|
lang | No | Optional response language code, for example en. Returned copy falls back according to community configuration. |
Understanding programs and stages
programId is the public identifier accepted by the summary endpoint's optional programId filter.stages are returned in their configured display order. Do not sort by names or infer a universal number of stages.mainConditionOperator, mainConditions, and nestedConditions describe configured milestone logic. Field keys and values differ by community.rewards is the reward for one stage; totalRewards is the configured sum for the program.Complete examples
200 examples show one synthetic configured program and the valid empty state. Treat their IDs, labels, conditions, and rewards as illustrative only.Success and readback
200, read data as the current public configuration snapshot. Confirm the expected programId, stage order, conditions, and rewards before treating a launch as configured. Re-read after an administrator changes the program; this endpoint does not report user progress.Errors and recovery
| Status | Recovery |
|---|---|
401 AUTH_API_KEY_REQUIRED | Add the server-side Bearer key. |
401 AUTH_API_KEY_INVALID | Replace an invalid or expired key. |
403 | Grant getUserData or use the intended community key. |
500 / 502 | Retry with bounded backoff and escalate if persistent. |
Empty and changed configurations
data: [] when no public referral program is active. Re-read this endpoint during launch checks and after referral administrators change program configuration.Retry safety
500, 502, and transient network failures; do not retry 400, 401, or 403 without correcting the request or key.Gotchas
WARNING
Next steps
Request
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/referral/programs?lang=en' \
--header 'Authorization: Bearer <COMMUNITY_API_KEY>'Response Response Example
200 - Success Example
{
"meta": {
"status": "success",
"statusCode": 200
},
"message": "Get referral programs success.",
"data": [
{
"enabled": true,
"programId": "64b7f3a2c8d4e6f102938471",
"name": "Invite and earn",
"description": "Earn configured rewards as invited members reach milestones.",
"color": "#4F46E5",
"icon": "users",
"stages": [
{
"stageId": "64b7f3a2c8d4e6f102938472",
"stageNumber": 1,
"name": "Member joins",
"description": "The invited member creates an eligible account.",
"displaySetting": "Show progress",
"mainConditionOperator": "AND",
"mainConditions": [
{
"groupId": "64b7f3a2c8d4e6f102938473",
"operator": "AND",
"nestedConditions": [
{
"conditionId": "64b7f3a2c8d4e6f102938474",
"key": "registration_status",
"type": "string",
"condition": "equals",
"value": "registered",
"enableUserFacingCondition": true,
"userFacingCondition": "Account created",
"valueLabel": "Registered",
"isDeletedValue": false
}
],
"enableUserFacingCondition": true,
"userFacingCondition": "Invited member joins"
}
],
"rewards": {
"xp": 250,
"coins": 25
}
}
],
"totalRewards": {
"xp": 250,
"coins": 25
}
}
]
}Modified at 2026-08-17 15:23:38