Get user's referral summary

What it is for: Returns a user's referral summary, including invite link, referral activity totals, referral program stage
progress, referred users, rewards earned, and pagination.

How to use it: Send a POST request to /apis/v1/referrals/summary with the request body shown below. Authorization: Bearer
<apiKey> in the Authorization header. 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 is wrapped as { "status": "success", "data": ... }. data contains the resolved
referrer, invite link, activity totals, enabled referral programs, paginated referred users, and pagination cursor.

Common error states:

400 invalid request body, invalid cursor, invalid programId, missing fieldName for custom-field, invalid custom-field
value, or unsupported custom-field identifier.

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

404 community not found, user not found, user does not belong to this community, or requested referral program was not
found.

409 duplicate users found for a custom-field identifier.

503 custom-field lookup is not ready.

500 unexpected Returning.AI service error.

curl --location 'https://adss-integration.returning.ai/apis/referral/summary' \ --header 'Authorization;' \ --header 'Content-Type: application/json' \ --data '{ "identifier": { "type": "custom-field", "value": "CUS-001", "fieldName": "customerId" }, "pagination": { "limit": 25 } }'

{ "meta": { "status": "string", "statusCode": 0 }, "message": "string", "data": { "user": { "id": "string", "userId": "string", "email": "string", "username": "string" }, "invite": { "code": "string", "origin": "string", "url": "string", "platformUrl": "string" }, "activity": { "coinsEarned": 0, "xpEarned": 0, "totalReferrals": 0, "inProgress": 0, "completed": 0 }, "referees": [ { "userId": "string", "username": "string", "avatar": "string", "joinedAt": "string", "progressByProgram": [ { "programId": "string", "programName": "string", "completedStages": 0, "totalStages": 0, "percentage": 0, "stages": [ { "stageId": "string", "stageNumber": 0, "name": "string", "description": "string", "displaySetting": "string", "status": "string", "isCompleted": true, "rewards": { "xp": 0, "coins": 0 }, "requirements": { "operator": "string", "met": 0, "total": 0, "mainConditions": [ { "groupId": "string", "operator": "string", "text": "string", "isMet": true, "nestedConditions": [ { "conditionId": "string", "text": "string", "isMet": true, "revoked": true, "isRaw": true } ], "revoked": true } ] }, "revoked": true } ] } ] } ], "totalCount": 0, "pagination": { "nextCursor": "string", "hasNextPage": true } } }

Request

Responses