Get user's referral summary
POST
/v1/referral/summary
What this endpoint does
INFO
200 with zero activity and referees: []. 404 User not found means identity resolution failed inside the API key's community; it does not mean the referral program is missing.Quick start
Authentication and permission
getUserData. Do not send communityId; the key fixes the tenant boundary. Missing, invalid, or expired keys return 401; a valid key without permission returns 403.Choose the same stable identity used at registration
identifier.type | value means | Extra field |
|---|---|---|
id | Returning.AI member ObjectId | None |
email | Stored member email | None |
data-email | Email-style external identity used by the integration or widget mapping | None |
data-customer-id | Stable broker or customer identity used by the integration or widget mapping | None |
cognito-sub | Stable Cognito subject stored for the member | None |
custom-field | Value stored in a named custom user field | fieldName is required |
custom-field, fieldName is required and must be the configured field's exact API name. A field label, a field from another community, or the referrer's identifier in place of the current member's identifier returns no match.Complete examples
200 example shows a valid member with zero activity. Values use synthetic example.com identities and do not represent a live community.Optional controls
pagination.limit: 1–100; default 20.pagination.cursor: opaque nextCursor from the previous response. Do not decode or manufacture it.programId: restrict progress to one public ID returned by Get referral programs.lang: optional response language code.Reading the response
user is the member whose summary was requested.invite.url is the configured client-facing invite URL. platformUrl is the Returning.AI fallback; do not assume they have the same origin or query shape.activity aggregates rewards and referral counts.referees[] contains the current page of invited members.progressByProgram[].stages[] carries completion state, configured rewards, and readable requirements.pagination.hasNextPage tells you whether to request another page. Send nextCursor back as pagination.cursor only when it is present.Success and readback
200 as a snapshot for the identified member. A zero-activity snapshot proves that the member resolved; it does not prove that an immediately preceding referral write has finished processing. For a populated dashboard, page until hasNextPage is false and deduplicate referees by stable returned identity.Eventual consistency and readback
Errors and recovery
| Status | Meaning | Recovery |
|---|---|---|
400 VALIDATION_FAILED | Missing or invalid identifier, custom-field without fieldName, or limit outside 1–100 | Correct the request; do not retry unchanged. |
401 | Missing, invalid, or expired API key | Replace or fix the Bearer key. |
403 | Key lacks getUserData | Grant permission or use the correct community key. |
404 User not found | No member matches that identifier in this key's community | Verify registration, tenant, identifier type, field name, and exact value. |
500 / 502 | Unexpected or upstream service failure | Retry with bounded backoff; escalate if persistent. |
AUTH_API_KEY_REQUIRED; invalid or expired keys use AUTH_API_KEY_INVALID.Retry safety
Gotchas
invite.url from platformUrl; use the configured client-facing URL when present.404 is an identity or tenant mismatch, not evidence that no referral program exists.Next steps
Request
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/referral/summary' \
--header 'Authorization: Bearer <COMMUNITY_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"identifier": {
"type": "data-customer-id",
"value": "broker-customer-10482"
},
"pagination": {
"limit": 20
}
}'Response Response Example
200 - Success Example
{
"meta": {
"status": "success",
"statusCode": 200
},
"message": "Get referral summary success.",
"data": {
"user": {
"id": "64b7f3a2c8d4e6f102938481",
"userId": "10482",
"email": "member@example.com",
"username": "member-10482"
},
"invite": {
"code": "member-10482:10482",
"origin": "https://community.example.com",
"url": "https://community.example.com/join?ref=broker-customer-10482",
"platformUrl": "https://community.returning.ai/register?ref=member-10482:10482"
},
"activity": {
"coinsEarned": 0,
"xpEarned": 0,
"totalReferrals": 0,
"inProgress": 0,
"completed": 0
},
"referees": [],
"totalCount": 0,
"pagination": {
"hasNextPage": false
}
}
}Modified at 2026-08-17 15:23:46