Get Referral Link

GET /api/v1/referral/link — 🔑 Bearer · Kill-switched

Returns the calling user's personal referral link. Get-or-create: first read generates a ReferralLink row (code derived from User.username, falling back to an 8-char UUID slice on collision); every subsequent read returns the existing row. There is at most one active ReferralLink per user (uniqueness enforced on ReferralLink.userId).

Request

No body, no params.

Response

200 OK — ApiResponseOf<ReferralLinkCodeResponseDto>

{
  "success": true,
  "data": {
    "code": "alice123",
    "link": "bio.re/ref/alice123"
  }
}

Errors

Side effects

1. referralLink.findUnique({ where: { userId } }). Existing row → return { code, link } directly.
2. No row — load User.username for the candidate code; fallback to randomUUID().slice(0, 8) if null.
3. Cross-table collision check (up to 3 attempts), run as one Promise.all:
   • user.findUnique({ where: { referralCode: code } }) — clash with someone's User.referralCode.
   • referralLinkAlias.findUnique({ where: { code } }) — clash with a preserved old vanity code from a previous rename.
   • On hit, regenerate with randomUUID().slice(0, 8) and retry.
   • 3rd failure → throw code_collision.
   • Note: collision against another ReferralLink.code is enforced by the unique constraint at referralLink.create() time and surfaces as Prisma P2002; explicit pre-checks cover the cross-table cases the unique index can't.
4. referralLink.create({ id, userId, code }).
5. Return { code, link: 'bio.re/ref/<code>' }.

Alias resolution

Any code passed to a referral lookup (e.g. POST /referral/click/:code, plus all auth/oauth signup callers that accept a referrer code) is resolved through the canonical alias-aware helper:

1. referralLink.findUnique({ where: { code } }) — direct hit on the live code.
2. If no direct hit: referralLinkAlias.findUnique({ where: { code }, include: { referralLink: true } }) — fall back to a preserved old vanity code.
3. Returns the underlying ReferralLink row in either case (or null if neither matches).

This means:

• A user's link has at most one live code (ReferralLink.code) but may have multiple aliases (one per past vanity rename — see Change Username · Referral code side-effect).
• Old shared URLs never break and keep crediting the original referrer.
• All counters (clicks, signups, conversions) and reward rows live on ReferralLink. Aliases carry no counters of their own — they only map code → referralLinkId — so click-traffic on bio.re/ref/<oldcode> and bio.re/ref/<newcode> aggregates to the same ReferralLink, with no double-counting.
• A code currently held by any of ReferralLink.code, ReferralLinkAlias.code, or User.referralCode cannot be claimed as a new link or rename target.

Code samples

curl https://api.bio.re/api/v1/referral/link \
  -H "Authorization: Bearer $ACCESS_TOKEN"

type ReferralLink = {
  code: string;
  link: string;
};

async function getReferralLink(accessToken: string): Promise<ReferralLink> {
  const res = await fetch('https://api.bio.re/api/v1/referral/link', {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    throw Object.assign(new Error(json?.error?.message ?? 'Referral link fetch failed'), {
      code: json?.error?.code,
    });
  }
  return json.data;
}

import { useQuery } from '@tanstack/react-query';

export const referralKeys = {
  link: () => ['referral', 'link'] as const,
};

export function useReferralLink() {
  return useQuery({
    queryKey: referralKeys.link(),
    queryFn: async () => {
      const res = await fetch('/api/v1/referral/link');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Referral link fetch failed'), {
          code: json?.error?.code,
          i18nKey: json?.error?.i18nKey,
        });
      }
      return json.data as ReferralLink;
    },
    // Code is stable per session but may change after a username rename
    // (vanity sync — see /docs/user/username#referral-code-side-effect).
    // Invalidate ['referral', 'link'] from the username-change mutation's onSuccess.
    staleTime: 60 * 60_000,
    gcTime: 60 * 60_000,
  });
}

Try it

curl -X GET "https://loading/api/v1/referral/link"

{
  "success": true,
  "data": {
    "code": "alice123",
    "link": "bio.re/ref/alice123"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Source