API reference / Gamification / Referral

Get referral programs

List the referral programs set up in the community that owns your API key, with each stage's requirements and rewards.

Last updated 26 Sep 2026API v1

Method: GET
Path: https://api.returning.ai/v1/referral/programs
Permission: getUserData
Retries: Read-only; exact retries are safe

When to use this

Show traders which referral programs exist, what each stage asks of the people they invite, and what it pays.
Check a program's stages and rewards before you launch it.
Find a programId to filter Get user's referral summary by.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: getUserDataShown in the dashboard as “Get User Data”

Send a Community API key with getUserData, shown in the dashboard as Get User Data. The key decides the community, so never send a community ID. Keep the key on your server.

Behaviour#

This read changes nothing and returns your programs as they are set up now, not any trader's progress. It includes programs that are switched off, so check enabled before you show one to traders. Programs with no stages and deleted programs are left out.

Condition keys, values and rewards differ between communities and change when an admin edits a program. Render what the response returns rather than hard-coding stage counts, names or amounts.

With a lang other than en, names, descriptions and requirement text come back translated. A translation that doesn't exist yet is made on the first request, which can make that request slower.

Request#

Query parameters#

lang#stringOPTIONAL

Language code for names, descriptions and requirement text, such as fr. Omit it, or send en, for the text as it was entered.

RuleLanguage code

Egen

Headers#

Authorization#stringREQUIRED

Community API key with getUserData.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/referral/programs?lang=en' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the programs in data. An empty data means your community has no referral programs with stages. Branch on the HTTP status.

meta#objectALWAYS

Status of the request.

Eg{"status": "success", "statusCode": 200}

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

Eg200

message#stringALWAYS

Human-readable summary. Do not branch on it.

Eg"Get referral programs success."

data#object[]ALWAYS

Every program in your community that has at least one stage, in the order set in the dashboard. Includes switched-off programs. An empty array when there are none.

Eg[ ... ]

programId#stringALWAYS

The program's ID. Send it as programId to Get user's referral summary.

Eg"66f000000000000000000710"

name#stringALWAYS

Program name.

Eg"Invite a trader"

description#stringALWAYS

Program description. Empty string when none.

Eg"Earn rewards as the traders you invite get started."

enabled#booleanALWAYS

true when the program is running. Switched-off programs are listed too, with false.

Egtrue

color#stringALWAYS

Display color, a hex code. Empty string when none.

Eg"#4F46E5"

icon#stringALWAYS

Icon set for the program. Empty string when none.

totalRewards#objectALWAYS

The bonus paid once an invited trader completes every stage, as xp and coins. It is paid on top of the stage rewards, not their sum. 0 when there is no bonus.

Eg{"xp": 0, "coins": 100}

xp#integerALWAYS

XP.

Eg0

coins#integerALWAYS

Coins.

Eg100

stages#object[]ALWAYS

The program's stages, in order.

Eg[ ... ]

stageId#stringALWAYS

The stage's ID.

Eg"66f000000000000000000711"

stageNumber#integerALWAYS

Position in the program, starting at 1.

Eg1

name#stringALWAYS

Stage name.

Eg"Get active"

description#stringALWAYS

Stage description. Empty string when none.

Eg"Your friend earns more than 500 XP."

displaySetting#stringALWAYS

What traders are shown for the stage.

Rulecondition, description or condition_and_description

Eg"condition"

rewards#objectALWAYS

What the referrer earns when an invited trader completes this stage, as xp and coins. 0 when that reward is off.

Eg{"xp": 250, "coins": 25}

xp#integerALWAYS

XP.

Eg250

coins#integerALWAYS

Coins.

Eg25

mainConditionOperator#stringALWAYS

and when every condition group must be met, or when one is enough.

Ruleand or or

Eg"and"

mainConditions#object[]ALWAYS

Condition groups for the stage.

Eg[ ... ]

groupId#stringALWAYS

The group's ID.

Eg"66f000000000000000000712"

operator#stringALWAYS

and when every condition in the group must be met, or when one is enough.

Ruleand or or

Eg"and"

enableUserFacingCondition#booleanALWAYS

true when the group's own text is shown to traders.

Egfalse

userFacingCondition#string

Text shown to traders for the group, when set.

nestedConditions#object[]ALWAYS

The conditions in the group.

Eg[ ... ]

conditionId#stringALWAYS

The condition's ID.

Eg"66f000000000000000000713"

key#stringALWAYS

What is checked about the invited trader, such as total_xp, messages_sent, role or one of your user fields.

Eg"total_xp"

type#stringALWAYS

The kind of value, such as number, date, role or tag.

Eg"number"

condition#stringALWAYS

The comparison, such as is, is_not, more_than, less_than, before or after.

Eg"more_than"

value#number, string or objectALWAYS

The value compared against. A number, text, or an object for ranges, depending on type.

Eg500

valueLabel#stringALWAYS

value in readable form, such as a role or tier name, or a formatted date.

Eg"500"

isDeletedValue#booleanALWAYS

true when value points to a role, tag, trader, tier or badge that no longer exists. valueLabel then reads Deleted Role, Deleted Tag and so on.

Egfalse

reference#object

Extra detail for conditions that compare against another field. Its shape depends on the condition; don't rely on it.

enableUserFacingCondition#booleanALWAYS

true when the condition's own text is shown to traders.

Egtrue

userFacingCondition#string

Text shown to traders for the condition, when set.

Eg"Earn more than 500 XP"

{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Get referral programs success.",
  "data": [
    {
      "enabled": true,
      "programId": "66f000000000000000000710",
      "name": "Invite a trader",
      "description": "Earn rewards as the traders you invite get started.",
      "color": "#4F46E5",
      "icon": "",
      "totalRewards": {
        "xp": 0,
        "coins": 100
      },
      "stages": [
        {
          "stageId": "66f000000000000000000711",
          "stageNumber": 1,
          "name": "Get active",
          "description": "Your friend earns more than 500 XP.",
          "displaySetting": "condition",
          "mainConditionOperator": "and",
          "mainConditions": [
            {
              "groupId": "66f000000000000000000712",
              "operator": "and",
              "enableUserFacingCondition": false,
              "nestedConditions": [
                {
                  "conditionId": "66f000000000000000000713",
                  "key": "total_xp",
                  "type": "number",
                  "condition": "more_than",
                  "value": 500,
                  "enableUserFacingCondition": true,
                  "userFacingCondition": "Earn more than 500 XP",
                  "valueLabel": "500",
                  "isDeletedValue": false
                }
              ]
            }
          ],
          "rewards": {
            "xp": 250,
            "coins": 25
          }
        }
      ]
    }
  ]
}

Errors#

401, 403 and 502 errors carry a code in meta.code. A 500 carries INTERNAL_ERROR, or no code at all with message Get referral programs error.; treat both the same. Branch on the HTTP status.

Fix the request03

401AUTH_API_KEY_REQUIREDFix the request

No key was sent. Send Authorization: Bearer <API_KEY>.

401AUTH_API_KEY_INVALIDFix the request

The key is unknown, expired or malformed. Use a current Community API key.

403AUTH_PERMISSION_REQUIREDFix the request

The key lacks getUserData. Add Get User Data in Settings > Integration > API Keys.

Retry with backoff03

502STORE_DEPENDENCY_UNAVAILABLERetry with backoff

Referral programs are briefly unavailable. Retry the same request with exponential backoff.

500INTERNAL_ERRORRetry with backoff

The read failed unexpectedly. Retry the same request with exponential backoff.

401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff

The key could not be checked just now. Retry with backoff; the key itself may be fine.

{
  "meta": {
    "status": "error",
    "statusCode": 401,
    "code": "AUTH_API_KEY_REQUIRED"
  },
  "message": "API key is required",
  "detail": "No Bearer token found in Authorization header",
  "solution": "Please provide a valid API key in the Authorization header as Bearer <key>"
}

Next step#

Get user's referral summaryPOST/v1/referral/summaryRead one trader's invite link and their invited traders' progress, optionally for one programId.

Find the trader to look up with Get User Data

Get referral programs

When to use this

01Authentication#

02Behaviour#

03Request#

Query parameters#

Headers#

04Response#

05Errors#

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#