Partner API

There are two ways to work with partners in code:

• As a partner: an API token (rpt_…) from the partner portal reads your own stats, links, referrals and payouts across every programme you're in, and creates links.

• As a merchant: your secret API key (rk_…) enrols your own users as partners and fetches their links, so you can put "Refer a friend" or "Refer a business" inside your product.

Partner API tokens

Create a token in the partner portal under Settings → API tokens. If you have two-factor sign-in on, it asks for a code. The token is shown once. Send it as a bearer token:

curl https://referalli.com/v1/partner/stats -H "Authorization: Bearer rpt_…"

A token never reaches your security settings, profile and payout details, KYC submission, contracts, advances, wallet sign-in or tax documents, whatever its access: those stay in a portal session. A token can't create, list or revoke tokens either. Any other call answers 403 and names the route.

• You can have at most 10 active tokens. Each can expire after 30, 90 or 365 days, or never (expiresInDays over the API).

• Revoke a token in the portal or with DELETE /v1/partner/api-tokens/{id}; it stops at once.

• Requests count against your usual partner rate limit.

# Your links, then a new one in a programme you're approved in (write token).
curl https://referalli.com/v1/partner/links -H "Authorization: Bearer $REFERALLI_PARTNER_TOKEN"
curl -X POST https://referalli.com/v1/partner/links -H "Authorization: Bearer $REFERALLI_PARTNER_TOKEN" \
  -H "content-type: application/json" \
  -d '{"orgId":"org_…","programId":"prg_…","destinationUrl":"https://merchant.example/pricing","code":"jane"}'

With an AI assistant (MCP)

The Referalli MCP server takes a partner token too. Set REFERALLI_API_KEY to your rpt_ token and it offers partner tools in place of the merchant ones: my_programs, my_stats, my_links, my_referrals, my_payouts, my_notifications and create_my_link. Like every MCP write, create_my_link previews first and asks for confirmation.

Enrolling your own users as partners

If your users refer others (customers referring customers, or a platform whose users bring other businesses), enrol them from your backend with your secret key. You don't need a partner signup.

1. Create or find the partner by your own user id. upsert: true returns the existing partner instead of a 409, so this is safe to call on every visit:

   curl -X POST https://referalli.com/v1/partners -H "Authorization: Bearer $REFERALLI_KEY" \
     -H "content-type: application/json" \
     -d '{"email":"jane@customer.example","displayName":"Jane","externalRef":"usr_123","upsert":true}'

2. Enrol them in the programme: POST /v1/programs/{programId}/enrollments with {"partnerId":"prt_…"}.

3. Create their link once, POST /v1/links with programId, partnerId and destinationUrl. After that, read it with GET /v1/links?partnerId=prt_… and show it in your app.

4. Show their earnings from GET /v1/partners/{id}/balances, or point them to the partner portal, where they sign in with the same email.

Keep this on your server: an rk_ key can do anything in your organization, and partners must never see it. To keep a key to just this, create it with the scopes partners:write, programs:write (enrolment), links:write and commissions:read (balances).