Referral growth

Ladders, boosts and gift links: what a referrer can reach and give away, to show in your referral screen.

Get a referrer’s ladders, boosts and gift links

GET/v1/referrals/growth

Everything to show on a user’s referral screen beyond their code: progress up each ladder, boosts running now or soon, whether they can send gifts, and the gift links they have made. Creates their referrer account on first use.

AuthSigned request with an app key, fg_live_… or fg_test_…

Query parameters

appUserIdstringrequired≤ 200 chars

Your pseudonymous id for the user. Never an email address or phone number.

Returns · 200

programIdstringrequireduuid

laddersarray of objectsrequired

Child attributes

ladderIdstringrequireduuid

campaignIdstringrequireduuid

campaignNamestringrequired

statusstringrequired

One of active paused

periodstringrequired

The window referrals are counted in. Calendar periods are UTC.

One of campaign month quarter year

periodKeystringrequired

periodStartstringrequireddate-time

periodEndstringrequireddate-timenullable

qualifiedintegerrequired

Qualified referrals counted toward the ladder in this period.

countsobjectrequired

Child attributes

registeredintegerrequired

verifiedintegerrequired

qualifiedintegerrequired

rejectedintegerrequired

levelstringrequirednullable

Label of the highest level reached.

tiersarray of objectsrequired

Child attributes

thresholdintegerrequired

Qualified referrals needed.

amountintegerrequired

Bonus in minor units; 0 for a level that carries no money.

currencystringrequired

labelstringrequirednullable

Level name, e.g. "Silver".

unlocksstringrequirednullable

A privilege the level brings; your app grants it.

statusstringrequired

reached: paid, or on its way, in this period.

One of reached open

reachedAtstringrequireddate-timenullable

nextobjectrequirednullable

Child attributes

thresholdintegerrequired

remainingintegerrequired

amountintegerrequired

Minor units.

currencystringrequired

labelstringrequirednullable

boostsarray of objectsrequired

Child attributes

idstringrequireduuid

campaignIdstringrequireduuid

namestringrequired

kindstringrequired

multiplier: multiplierBps / 10000 times the reward (20000 is double). fixed: amount on top.

One of multiplier fixed

multiplierBpsintegerrequirednullable

amountintegerrequirednullable

currencystringrequired

appliesTostringrequired

One of referrer referred_user both

startsAtstringrequireddate-time

endsAtstringrequireddate-time

marketsarray of stringsrequired

Countries it applies to; empty for all.

segmentsarray of stringsrequired

metadata.segment values of the invited user’s registration it applies to; empty for all.

livebooleanrequired

Running now; otherwise it starts within a week.

giftobjectrequirednullable

Null when no campaign offers gift links.

Child attributes

availablebooleanrequired

False when this referrer may not send gifts.

campaignIdstringrequireduuid

limitsobjectrequired

Child attributes

maxUsesPerLinkintegerrequired

expiryDaysintegerrequired

maxActiveLinksintegerrequired

maxLinksPerDayintegerrequired

termsobjectrequired

Show these to both people whenever a gift is offered.

Child attributes

friendGetsobjectrequired

Child attributes

amountintegerrequired

Minor units.

currencystringrequired

fundedBystringrequired

referrer: the gift is taken out of the referrer’s own reward for this friend.

One of campaign referrer

qualifyingEventsarray of stringsrequired

Event types the friend must complete; the gift follows the first.

withinDaysintegerrequirednullable

referrerGetsarray of objectsrequired

What the referrer gets for the same friend, after any part given away as the gift.

Child attributes

ruleNamestringrequired

triggerEventstringrequired

modelstringrequired

One of fixed percentage

amountintegerrequirednullable

percentBpsintegerrequirednullable

currencystringrequired

reducedByintegerrequired

The part of the referrer’s reward that becomes the friend’s gift.

expiresAtstringrequireddate-timenullable

maxUsesintegerrequirednullable

giftLinksarray of objectsrequired

The referrer’s latest 50 gift links, newest first.

Child attributes

idstringrequireduuid

codestringrequired

urlstringrequireduri

Share this. It keeps working as the referrer’s link after the gift has run out.

campaignIdstringrequireduuid

amountintegerrequired

Minor units.

currencystringrequired

fundingstringrequired

One of campaign referrer

maxUsesintegerrequired

usesintegerrequired

expiresAtstringrequireddate-time

statusstringrequired

One of active used_up expired revoked

notestringrequirednullable

createdAtstringrequireddate-time

termsobjectrequired

Show these to both people whenever a gift is offered.

Child attributes

friendGetsobjectrequired

Child attributes

amountintegerrequired

Minor units.

currencystringrequired

fundedBystringrequired

referrer: the gift is taken out of the referrer’s own reward for this friend.

One of campaign referrer

qualifyingEventsarray of stringsrequired

Event types the friend must complete; the gift follows the first.

withinDaysintegerrequirednullable

referrerGetsarray of objectsrequired

What the referrer gets for the same friend, after any part given away as the gift.

Child attributes

ruleNamestringrequired

triggerEventstringrequired

modelstringrequired

One of fixed percentage

amountintegerrequirednullable

percentBpsintegerrequirednullable

currencystringrequired

reducedByintegerrequired

The part of the referrer’s reward that becomes the friend’s gift.

expiresAtstringrequireddate-timenullable

maxUsesintegerrequirednullable

Errors

400validation_error: The request does not match the schema. details says which fields failed and why.
401missing_signature: One of x-fg-key, x-fg-timestamp and x-fg-signature is missing.
401invalid_timestamp: x-fg-timestamp is not Unix time in seconds.
401stale_timestamp: x-fg-timestamp is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.
401invalid_key: The key id is unknown or revoked, or the app is archived.
401invalid_signature: The signature does not match. Sign the exact bytes you send.
404not_found: Your app has no active friend-referral program.
429too_many_attempts: Too many requests with this key in the last minute. Wait Retry-After seconds.

Request

TS=$(date +%s)
SIG=$(printf '%s.' "$TS" | openssl dgst -sha256 -hmac "$FG_SECRET" | sed 's/^.*= //')

curl "https://api.flowgroup.se/v1/referrals/growth?appUserId=u_1042" \
  -H "x-fg-key: $FG_KEY_ID" \
  -H "x-fg-timestamp: $TS" \
  -H "x-fg-signature: $SIG"

import { createFlowGrowth } from '@flow/growth-sdk';

const fg = createFlowGrowth({
  baseUrl: 'https://api.flowgroup.se',
  keyId: process.env.FG_KEY_ID!, // fg_test_… in the sandbox
  secret: process.env.FG_SECRET!,
});

const res = await fg.getReferralGrowth('u_1042');
if (res.ok) console.log(res.data.ladders, res.data.giftLinks);

200 OK

{
  "programId": "0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a",
  "ladders": [],
  "boosts": [],
  "gift": null,
  "giftLinks": []
}

List active boosts

GET/v1/referrals/boosts

Boosts on your friend-referral program that run now or start within a week.

AuthSigned request with an app key, fg_live_… or fg_test_…

Query parameters

countrystring

ISO 3166 alpha-2. Only boosts that apply there are returned.

Matches ^[A-Z]{2}$

Returns · 200

itemsarray of objectsrequired

Child attributes

idstringrequireduuid

campaignIdstringrequireduuid

namestringrequired

kindstringrequired

multiplier: multiplierBps / 10000 times the reward (20000 is double). fixed: amount on top.

One of multiplier fixed

multiplierBpsintegerrequirednullable

amountintegerrequirednullable

currencystringrequired

appliesTostringrequired

One of referrer referred_user both

startsAtstringrequireddate-time

endsAtstringrequireddate-time

marketsarray of stringsrequired

Countries it applies to; empty for all.

segmentsarray of stringsrequired

metadata.segment values of the invited user’s registration it applies to; empty for all.

livebooleanrequired

Running now; otherwise it starts within a week.

Errors

400validation_error: The request does not match the schema. details says which fields failed and why.
401missing_signature: One of x-fg-key, x-fg-timestamp and x-fg-signature is missing.
401invalid_timestamp: x-fg-timestamp is not Unix time in seconds.
401stale_timestamp: x-fg-timestamp is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.
401invalid_key: The key id is unknown or revoked, or the app is archived.
401invalid_signature: The signature does not match. Sign the exact bytes you send.
429too_many_attempts: Too many requests with this key in the last minute. Wait Retry-After seconds.

Request

TS=$(date +%s)
SIG=$(printf '%s.' "$TS" | openssl dgst -sha256 -hmac "$FG_SECRET" | sed 's/^.*= //')

curl "https://api.flowgroup.se/v1/referrals/boosts" \
  -H "x-fg-key: $FG_KEY_ID" \
  -H "x-fg-timestamp: $TS" \
  -H "x-fg-signature: $SIG"

import { createFlowGrowth } from '@flow/growth-sdk';

const fg = createFlowGrowth({
  baseUrl: 'https://api.flowgroup.se',
  keyId: process.env.FG_KEY_ID!, // fg_test_… in the sandbox
  secret: process.env.FG_SECRET!,
});

const res = await fg.getActiveBoosts('SE');

200 OK

{
  "items": [
    {
      "id": "3f1c8a52-6c1e-4b8e-9d0a-2b7f0c4e5a91",
      "campaignId": "3f1c8a52-6c1e-4b8e-9d0a-2b7f0c4e5a91",
      "name": "name",
      "kind": "multiplier",
      "multiplierBps": 1,
      "amount": 2500,
      "currency": "USD",
      "appliesTo": "referrer",
      "startsAt": "2026-11-09T12:00:00.000Z",
      "endsAt": "2026-11-09T12:00:00.000Z",
      "markets": [
        "markets"
      ],
      "segments": [
        "segments"
      ],
      "live": true
    }
  ]
}

Create a gift link

POST/v1/referrals/gift-links

Makes a gift link for one of your users to send to a friend, within the campaign’s limits. The friend gets the gift when they complete a qualifying event.

AuthSigned request with an app key, fg_live_… or fg_test_…

Request body

appUserIdstringrequired≤ 200 chars

Your pseudonymous id for the user. Never an email address or phone number.

notestring≤ 140 chars

A note for the referrer, e.g. who the gift is for. Never shown to the friend.

Returns · 201

A link a referrer sends to one or a few friends, carrying a welcome gift.

idstringrequireduuid

codestringrequired

urlstringrequireduri

Share this. It keeps working as the referrer’s link after the gift has run out.

campaignIdstringrequireduuid

amountintegerrequired

Minor units.

currencystringrequired

fundingstringrequired

One of campaign referrer

maxUsesintegerrequired

usesintegerrequired

expiresAtstringrequireddate-time

statusstringrequired

One of active used_up expired revoked

notestringrequirednullable

createdAtstringrequireddate-time

termsobjectrequired

Show these to both people whenever a gift is offered.

Child attributes

friendGetsobjectrequired

Child attributes

amountintegerrequired

Minor units.

currencystringrequired

fundedBystringrequired

referrer: the gift is taken out of the referrer’s own reward for this friend.

One of campaign referrer

qualifyingEventsarray of stringsrequired

Event types the friend must complete; the gift follows the first.

withinDaysintegerrequirednullable

referrerGetsarray of objectsrequired

What the referrer gets for the same friend, after any part given away as the gift.

Child attributes

ruleNamestringrequired

triggerEventstringrequired

modelstringrequired

One of fixed percentage

amountintegerrequirednullable

percentBpsintegerrequirednullable

currencystringrequired

reducedByintegerrequired

The part of the referrer’s reward that becomes the friend’s gift.

expiresAtstringrequireddate-timenullable

maxUsesintegerrequirednullable

Errors

400validation_error: The request does not match the schema. details says which fields failed and why.
401missing_signature: One of x-fg-key, x-fg-timestamp and x-fg-signature is missing.
401invalid_timestamp: x-fg-timestamp is not Unix time in seconds.
401stale_timestamp: x-fg-timestamp is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.
401invalid_key: The key id is unknown or revoked, or the app is archived.
401invalid_signature: The signature does not match. Sign the exact bytes you send.
403referrer_blocked: This referrer is suspended or blocked and cannot send gifts.
404not_found: Your app has no active friend-referral program.
409gifts_unavailable: No campaign of the program offers gift links right now.
409gift_link_limit: The referrer already has as many open gift links as the campaign allows.
409gift_limit_reached: The referrer has given away as much as the campaign allows.
429gift_link_daily_limit: The referrer has made as many gift links today as the campaign allows.
429too_many_attempts: Too many requests with this key in the last minute. Wait Retry-After seconds.

Request

BODY='{"appUserId":"u_8F2K","note":"For Sara"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$FG_SECRET" | sed 's/^.*= //')

curl -X POST "https://api.flowgroup.se/v1/referrals/gift-links" \
  -H "content-type: application/json" \
  -H "x-fg-key: $FG_KEY_ID" \
  -H "x-fg-timestamp: $TS" \
  -H "x-fg-signature: $SIG" \
  --data-raw "$BODY"

import { createFlowGrowth } from '@flow/growth-sdk';

const fg = createFlowGrowth({
  baseUrl: 'https://api.flowgroup.se',
  keyId: process.env.FG_KEY_ID!, // fg_test_… in the sandbox
  secret: process.env.FG_SECRET!,
});

const res = await fg.createGiftLink({ appUserId: 'u_1042', note: 'For Sara' });
if (res.ok) share(res.data.url);

201 Created

{
  "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "code": "gq4m8z2r",
  "url": "https://go.affiliate.yflow.io/a/gq4m8z2r",
  "campaignId": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
  "amount": 100,
  "currency": "USD",
  "funding": "referrer",
  "maxUses": 1,
  "uses": 0,
  "expiresAt": "2026-11-23T09:30:00.000Z",
  "status": "active",
  "note": "For Sara",
  "createdAt": "2026-11-09T09:30:00.000Z",
  "terms": {
    "friendGets": {
      "amount": 100,
      "currency": "USD"
    },
    "fundedBy": "referrer",
    "qualifyingEvents": [
      "purchase.completed"
    ],
    "withinDays": 30,
    "referrerGets": [
      {
        "ruleName": "Friend makes a first purchase",
        "triggerEvent": "purchase.completed",
        "model": "fixed",
        "amount": 100,
        "percentBps": null,
        "currency": "USD",
        "reducedBy": 100
      }
    ],
    "expiresAt": "2026-11-23T09:30:00.000Z",
    "maxUses": 1
  }
}

Revoke a gift link

POST/v1/referrals/gift-links/{id}/revoke

Stops a gift link from carrying a gift. Friends who already used it keep theirs, and the link keeps working as the referrer’s own link.

AuthSigned request with an app key, fg_live_… or fg_test_…

Path parameters

idstringrequireduuid

The gift link’s id.

Request body

appUserIdstringrequired≤ 200 chars

Your pseudonymous id for the user. Never an email address or phone number.

Returns · 200

idstringrequireduuid

statusstringrequired

One of active used_up expired revoked

Errors

400validation_error: The request does not match the schema. details says which fields failed and why.
401missing_signature: One of x-fg-key, x-fg-timestamp and x-fg-signature is missing.
401invalid_timestamp: x-fg-timestamp is not Unix time in seconds.
401stale_timestamp: x-fg-timestamp is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.
401invalid_key: The key id is unknown or revoked, or the app is archived.
401invalid_signature: The signature does not match. Sign the exact bytes you send.
404not_found: The user has no gift link with this id, or your app has no active friend-referral program.
429too_many_attempts: Too many requests with this key in the last minute. Wait Retry-After seconds.

Request

BODY='{"appUserId":"u_8F2K"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$FG_SECRET" | sed 's/^.*= //')

curl -X POST "https://api.flowgroup.se/v1/referrals/gift-links/3f1c8a52-6c1e-4b8e-9d0a-2b7f0c4e5a91/revoke" \
  -H "content-type: application/json" \
  -H "x-fg-key: $FG_KEY_ID" \
  -H "x-fg-timestamp: $TS" \
  -H "x-fg-signature: $SIG" \
  --data-raw "$BODY"

import { createFlowGrowth } from '@flow/growth-sdk';

const fg = createFlowGrowth({
  baseUrl: 'https://api.flowgroup.se',
  keyId: process.env.FG_KEY_ID!, // fg_test_… in the sandbox
  secret: process.env.FG_SECRET!,
});

const res = await fg.revokeGiftLink({ appUserId: 'u_1042', id: giftLinkId });

200 OK

{
  "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "status": "revoked"
}

Get a referrer’s ladders, boosts and gift links#

List active boosts#

Create a gift link#

Revoke a gift link#

Get a referrer’s ladders, boosts and gift links

List active boosts

Create a gift link

Revoke a gift link