Attribution
How an install becomes a referral, what happens when two inviters claim one person, and how someone who signs up a week later still counts.
Referrals does not do its own matching. When an install arrives, Links has already decided which link it came from and how confidently. Referrals reads that decision.
From tap to referral
The personal link is an ordinary Vouch link carrying two parameters that identify the programme and
the inviter. On install, Links matches the device to the link, Referrals sees those parameters, and
a referral is created in pending.
The referral records the match type it inherited:
| Match type | Deterministic | How |
|---|---|---|
install_referrer | Yes | Android carried a signed token through Google Play. |
clipboard | Yes | iOS carried a signed token via the clipboard, if you enabled it. |
session | Yes | The person was signed in on the web before installing. |
code | Yes | They typed the code into your app. |
probabilistic | No | Inferred from one unambiguous device fingerprint. |
A programme refuses probabilistic unless you set allow_probabilistic. When you do allow it, the
referral is still labelled, so you can always separate what you know from what you inferred.
When two inviters claim one person
Someone can tap two different invite links before installing. Only one inviter can be credited, and
conflict_policy decides which.
| Policy | Chooses |
|---|---|
first_click | The earliest claim. |
last_click | The most recent claim. |
deterministic_first | A token-backed match over an inferred one, falling back to the most recent. |
deterministic_first is the default and usually the right answer: it prefers the claim you can
prove over the one you guessed.
Signing up later
Most people do not create an account the moment they install. When your app calls identify, Vouch binds the referral to your own user id permanently, and re-runs the conditions.
That binding is what makes later events count. Until it happens, a purchase reported against your user id has no referral to attach to. If you take one thing from this page: call identify as soon as you know who the user is, even if the referral qualified on install alone.
Late sign-up qualifies for as long as the programme's attribution_window_days allows, 30 days by
default.
A referral that is attributed but never bound to a user will sit in pending for ever. It is the
most common integration mistake, and the Referrals table in the dashboard shows it as an
attributed referral with no invitee.
Telling Vouch about purchases
Conditions like first_purchase and trial_started need to know what your users bought. Report it
from your server with a secret key.
curl -X POST https://api.vouch.dev/v1/conversions \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{
"app_id": "app_123",
"external_user_id": "user_456",
"type": "purchase",
"amount_minor": 4900,
"currency": "GBP",
"source": "api",
"source_transaction_id": "ch_1234567890"
}'type is one of lead, trial, purchase, renewal, refund or cancel. source is store,
web or api.
Conversions are idempotent per source_transaction_id, so retrying a webhook cannot pay a reward
twice. Amounts are integer minor units with a currency; there are no floating point amounts
anywhere in the API.
Every conversion re-runs qualification for that user's referral. The referral row is locked while that happens, so two conversions arriving together cannot both trigger a payout.
Redeeming a code
If someone types a code instead of following a link, your app sends it and the referral is created
the same way, with match type code.
A referral created from a code has no click behind it, which is why codes are counted separately in reporting rather than inflating the funnel.