Skip to documentation
AdQuestDocs

Referral evidence

API type: referral. Own-platform only. Your server reports each signup with the inviter’s code; AdQuest attributes it and pays.

On this page

What you do

  1. Show each inviter their code: with the inviter’s participant session, read getGrowthStatus(questId). referral.code is the code and referral.attributedCount the friends counted so far.

  2. With AdQuest codes, put the code on the link they share, such as https://your-app.example/join?adquest_ref=ABC123XYZ0, and keep it through your signup. With Platform codes there is no invite link (inviteLink is empty) and the widget shares your own code: see Use your own invite codes below.

  3. When the new account is created, your server reports the quest’s signup activity with that code as referral_code.

  4. AdQuest counts the friend for the inviter, and pays whoever the quest rewards once the minimum number of friends is reached. A quest set to pay for each invite completes at the first friend and pays each counted friend separately: see Pay for each invite below.

Report a signup with the invite code — using reportActivities from Report activities
await reportActivities([
  // id allows only letters, digits, _ . : and -. Use your own numeric account id, not an email or a free-form user id.
  { id: "signup_" + accountId, type: "user.signed_up", user: externalUserId, occurred_at: Math.floor(Date.now() / 1000), referral_code: referralCode },
]);

Use your own invite codes

  1. In the quest, set Invite codes to Platform. AdQuest then issues no codes or invite links for it.

  2. Send each participant’s own code as referral_code when you create their participant session. A code moves to the last user it is sent for; each user holds one. The rules are under Participant sessions, referral code.

  3. Register the codes of users who never opened the widget with POST /server/referral-codes, up to 500 per request. Users AdQuest has not seen yet are created.

  4. Report signups exactly as above, with your code as referral_code. A code must be registered before the signup is reported.

Register codes from your server — using serverRequest from Report activities
await serverRequest("POST", "/server/referral-codes", {
  codes: [{ user: "user_123", code: "ALI2024" }],
});

data.results answers each item in order: assigned with its referral_code, or rejected with code INVALID_USER (missing or longer than 255 characters), INVALID_REFERRAL_CODE (not 1 to 32 letters or digits) or DUPLICATE_IN_BATCH. When two items in one request name the same user or the same code, neither is applied.

Pay for each invite

  • When the publisher chose to pay for each invite, the first counted friend completes the quest. From then on each counted friend is paid separately, but only after the inviter’s own completion.
  • An inviter is paid for at most min_attributions friends, and never more than the reward’s max_billable_units.
  • A friend counted while the quest is paused or ended is recorded but not paid.
  • The growth-status API response shows referral.pay_each_invite, referral.paid_units (friends paid so far) and referral.max_units (the most that can be paid), and each history item has payout_unit: its paid number, or null. getGrowthStatus in the SDK does not return these fields.

Check before publishing

  • Test with two different accounts. A user’s own code never counts.
  • An account or device already counted for another invite does not count again.
  • A signup from before the quest went live, or outside its attribution window, does not count.
  • The invited friend never sends anything to AdQuest. Only your server reports the signup.

Next steps

Something unclear, missing or wrong here? Tell us