Get 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://api.returning.ai/v1/referrals/summary' \ --header 'Authorization;' \ --header 'Content-Type: application/json' \ --data '{ "identifier": { "type": "custom-field", "value": "CUS-001", "fieldName": "customerId" }, "pagination": { "limit": 25 } }'

Request

Responses