Analytics

The Overview page in the dashboard and the analytics routes of the API show the same numbers, worked out the same way. Use the dashboard to look, and the API to put the numbers in your own tools.

The routes

`GET /v1/analytics/funnel`	The funnel steps and the headline numbers.
`GET /v1/analytics/timeseries`	Clicks, installs, conversions and rewards per day or week.
`GET /v1/analytics/top-referrers`	Who referred the most people, by your own user id.
`GET /v1/analytics/channels`	Clicks, installs and conversions by share channel.

All four need a secret key and answer for that key's project and environment. They take from and to, as dates or timestamps. Without them you get the last 30 days. A period can be at most 366 days. Days and weeks are in UTC. Full details are in the API reference.

curl "https://api.referralpanda.com/v1/analytics/funnel?from=2026-11-01&to=2026-12-01" \
  -H "Authorization: Bearer rp_sk_live_..."

{
  "from": "2026-11-01T00:00:00.000Z",
  "to": "2026-12-01T00:00:00.000Z",
  "steps": {
    "screen_views": 120, "shares": 40, "link_clicks": 65,
    "installs": 22, "signups": 18, "conversions": 9, "rewarded": 6
  },
  "referrals": 23,
  "voided": 1,
  "rewards_issued": 11,
  "active_customers": 310,
  "referred_revenue": [{ "currency": "USD", "amount_minor": 8991 }],
  "reward_cost": [{ "currency": "USD", "amount_minor": 6000 }]
}

The funnel

`screen_views`	Times your app showed a referral screen (the SDK records this).
`shares`	Times someone tapped share.
`link_clicks`	Times a share link was opened.
`installs`	New users matched to the person who referred them.
`signups`	Referrals that began in the period and have reached sign-up or further.
`conversions`	Of those, the ones whose purchase met your program rule.
`rewarded`	Of those, the ones whose rewards have gone out.

The first four steps count things that happened in the period. The last three follow the referrals that began in the period and say how far they have come by now, so a referral from last week that converts today moves up in last week's numbers. Voided referrals are left out of those three and reported as voided.

The headline numbers

K-factor is installs divided by active_customers: new users gained through referrals for each customer your app saw in the period. Above 1, referrals alone would grow your app.
Referred revenue is what referred customers paid in the period, as reported by your purchase provider, with refunds taken off.
Reward cost is the value of rewards issued in the period that have a money value, such as gift cards. Free months and offer codes are counted in rewards_issued but have no cost here.
Cost per conversion is reward cost divided by conversions.

Money is always whole minor units (cents) with its currency, one entry per currency. We never add different currencies together or convert between them. The API returns the parts of each ratio and leaves the division to you.

One referral in detail

To find a referral, pass q to GET /v1/referrals with one of your own user ids or a referral code. You get the referrals where that person is the referrer or the friend. It has to be the whole id or code.

GET /v1/referrals/{id}/timeline then tells the story of one referral, oldest first: the link click, how the friend was matched, sign-up, purchases and refunds, each change of status, every step of each reward, and any fraud signals. The Referrals tab in the dashboard shows the same list and the same timeline.

One customer, and rewards by hand

Pass q to GET /v1/customers the same way to look one person up. Each customer comes with their referral_code, and GET /v1/rewards?recipient_customer_id= lists what they have earned. The Customers tab in the dashboard shows the same.

POST /v1/rewards gives a customer one of your rewards outside any referral, for example when a real referral was not tracked. Send the customer, the reward definition and a reason, with an Idempotency-Key header so a retry grants once. The amount is always the reward definition's own. The reward is approved at once and sent like any other, with no hold. It does not count toward program limits, and it does count in reward cost.

A reward that has not started sending can be voided with POST /v1/rewards/{id}/void, and a referral with POST /v1/referrals/{id}/void, which also accepts a note in your own words. In the dashboard both ask for a reason first. Nothing is edited or deleted: a grant and a void are each a new entry in the ledger, with who made it.

Rewards and their webhook events carry source (referral or manual). For a manual grant referral_id is null, so check for that if your code reads it.

Exports

GET /v1/exports/referrals and GET /v1/exports/rewards return a CSV file for a period (from and to, at most 366 days, the last 30 by default). Referrals can be narrowed with status and rewards with state. The Export CSV links on the Referrals and Rewards tabs download the same files for the last 12 months.

People appear as the user ids your app gave us, plus the referrer's code. No customer attributes are included.
Amounts are whole minor units (cents) in amount_minor, next to their currency.
Offer codes and payout links are never in an export.
A value that a spreadsheet would run as a formula starts with a single quote, so it opens as text.

Good to know

Sandbox and production are counted separately. A test key only ever sees sandbox.
Top referrers are listed by the user id your app gave us. No email address or other personal detail is returned.
Channels come from the share link that was opened. Links shared without a channel are grouped under null.
Answers may be up to a minute old.