Use this guide to connect a broker, membership platform, or customer portal to a Returning.AI referral program without coupling the integration to one community's field names, milestones, reward amounts, or page design.Keep community API keys server-side. Do not put them in browser code, mobile bundles, query strings, logs, screenshots, or analytics events.
1. Confirm the active program#
at least one expected program is enabled;
stages appear in the intended display order;
each user-facing condition describes the intended milestone;
stage and total rewards match the approved configuration;
the response is from the same community and environment used for registration.
data: [] means the API call worked but no public referral program is active.2. Choose one stable member identity#
Pick a broker-owned identifier that does not change when a member updates their name or email. Examples include a customer number, account UUID, or identity-provider subject. Confirm how that value maps to Returning.AI before launch.Use the same identity consistently in four places:1.
the member's Returning.AI registration;
2.
the invite-link dynamic value;
3.
the new referee's top-level referral value;
4.
later summary and widget lookups.
The new user's own stable identifier and the referrer's stable identifier are different values. Store the new user's own identifier on the new user. Send the referrer's identifier only in the referral relationship field.
invite.url and a Returning.AI fallback platformUrl.A client-facing template usually contains one dynamic value, for example:https://portal.example.com/join?ref={{stable_member_id}}
broker-customer-10482 requests their summary, the rendered URL might be:https://portal.example.com/join?ref=broker-customer-10482
ref, and do not reconstruct the URL when invite.url is already returned.4. Capture the referral before registration#
When a visitor arrives through an invite link, capture the referral value before registration starts. Preserve it through redirects, email verification, identity-provider callbacks, and multi-step onboarding. Validate the value as data; never execute or interpolate it into code.send the new user's own stable identifier in the configured member field;
if the visitor was referred, send the referrer's stable identifier in the top-level referral field;
do not copy the referrer's identifier into the new user's own identity field;
omit the referral field entirely for an organic, non-referred member.
{
"email": "new-member@example.com",
"customFields": [
{
"fieldIdorName": "brokerAccountId",
"value": "broker-customer-20491"
}
],
"referral": "broker-customer-10482"
}
5. Send milestone signals through the member lifecycle#
Referral stages evaluate configured conditions. A stage might represent registration, account approval, first deposit, first purchase, or another community-specific milestone.Do not invent a separate referral-trigger write. Send the real business state through the normal user creation, user update, custom-field, event, or workflow path agreed for the community. The referral service evaluates that state against the current program.For later member changes, use the documented Update User Data or the approved workflow for the configured condition field. Verify the saved user state before expecting a referral stage to complete.A boolean or status field belongs to the referred member whose action occurred. Do not set a milestone true merely to force a reward, and do not send a referrer's status as the referee's status.
6. Read the current member's referral summary#
{
"identifier": {
"type": "data-customer-id",
"value": "broker-customer-10482"
},
"pagination": {
"limit": 20
}
}
custom-field only when the identity is stored in a named custom field, and then include the exact fieldName. A valid member with no referrals returns 200, zero counters, and an empty referees array.7. Handle eventual consistency and pagination#
User creation, referral association, condition evaluation, and reward aggregation can complete asynchronously. After a write:1.
read the member back by the same stable identity;
2.
poll the referral summary with bounded backoff;
3.
stop when the expected referee or stage appears, or when the test timeout is reached;
4.
record the last response and correlation context before escalating.
pagination.hasNextPage is true, pass the returned opaque nextCursor as the next request's pagination.cursor. Do not decode it, change it, or reuse it with a different member, program filter, or community key.Retry and idempotency rules#
Programs and summary reads are idempotent. They are safe to retry with bounded backoff.
Do not blindly retry user creation. A timeout may hide a successful create and a second submission can conflict or duplicate downstream work. Read by the stable identifier first.
Do not replay milestone writes merely because summary propagation is delayed. Read the saved user state and poll summary before resubmitting.
Keep a caller-owned correlation ID in logs, but do not claim it is an API idempotency key unless the specific write endpoint documents that behavior.
End-to-end acceptance matrix#
Use disposable synthetic members in staging.| Case | Setup | Expected summary |
|---|
| Referrer only | Create a member with no referral | 200, invite URL present, zero activity, no referees |
| Joined referee | Create a second member with the referrer's stable ID | Referee appears; registration stage completes when configured |
| Qualified referee | Send the configured milestone on the referred member | Later stage and corresponding reward complete |
| Negative control | Create an otherwise similar member without a referral | Member does not appear in the referrer's summary |
| Unknown member | Query a synthetic identifier that was never registered | 404 User not found |
| Pagination | Create enough referred members to exceed a small limit | hasNextPage and nextCursor advance without duplicates |
Do not run reward-bearing production acceptance tests without an approved test user, reward boundary, and cleanup decision.Launch checklist#
Troubleshooting#
401 API key is required or Invalid API key#
Confirm the Authorization: Bearer <COMMUNITY_API_KEY> header, environment, expiration, and secret injection. Do not paste the key into a ticket or browser console.403 permission error#
The key is valid but lacks getUserData. Update the key's permissions or use the intended integration key.404 User not found#
Check that the member exists in the API key's community and that identifier.type, value, and optional fieldName match registration exactly. Do not switch identifier types until the mapping is confirmed.Invite URL contains the wrong member value#
Verify that the invite template uses the referrer's own stable identity field and that the field was populated before summary rendering.Referee does not appear#
Verify capture-before-registration ordering, read the new member back, confirm the top-level referral value is the referrer's identity, and allow bounded time for asynchronous association.Stage remains in progress#
Read the referred member's saved business state, compare it with the current program conditions, and confirm the signal was written to the referred member in the expected type and environment.Negative-control member is counted#
Stop launch. The organic member should have no referral relationship. Capture the sanitized create request shape and summary evidence, then escalate the attribution defect.API references#
