Get referral programs

What it is for: Returns public referral program definitions for the API key’s community. Clients can use this to build their
own referral program/stage UI alongside the referral summary API.

How to use it: Send a GET request to /apis/partner/referral/programs. Authorization: Bearer <apiKey>. The key must be
active, unexpired, scoped to the correct community, and include the permission required by this endpoint.
Required permission: getUserData.

Successful response: HTTP 200. The body follows the standard partner response envelope; useful payload is under data. data
is an array of enabled, non-deleted referral programs for the API key’s community.

Common error states:

400 invalid query parameter.

401 missing, invalid, expired, or insufficient API key/token.

403 key is valid but missing getUserData permission or cannot access this community.

502 referral service unavailable or upstream service communication failed.

500 unexpected Returning.AI service error.

{ "meta": { "status": "string", "statusCode": 0 }, "message": "string", "data": [ { "enabled": true, "programId": "string", "name": "string", "description": "string", "color": "string", "icon": "string", "totalRewards": { "xp": 0, "coins": 0 }, "stages": [ { "stageId": "string", "stageNumber": 0, "name": "string", "description": "string", "displaySetting": "string", "mainConditionOperator": "string", "mainConditions": [ { "groupId": "string", "operator": "string", "nestedConditions": [ { "conditionId": "string", "key": "string", "type": "string", "condition": "string", "value": 0, "enableUserFacingCondition": true, "userFacingCondition": "string", "valueLabel": "string", "isDeletedValue": true } ], "enableUserFacingCondition": true, "userFacingCondition": "string" } ], "rewards": { "xp": 0, "coins": 0 } } ] } ] }

Request

Responses