Guides

Referrals

Each person who joins gets a link to share. You decide what they and their friends get.

Use your agent. Paste this into it:

Read hunchwire.com/docs/referrals and turn on referrals for my waitlist.

On this page

Referrals

Each person who joins gets a link to share (?ref=<code>). The project decides what both sides get when a friend joins through it. The line, Analytics' referrals, and People's place and friends follow from that.

Hunchwire records codes even while referrals are off, so links already shared work the day you turn them on.

A friend counts for the person who shared only once both have confirmed. An email confirms by the link Hunchwire sends. A number confirms when your product sends confirmed (see API).

People can share before they confirm. Until they do, their confirmed friends are pending, and nothing they'd earn applies: no places, milestones or access. It all applies the moment they confirm.

Referrals need confirmation emails. A project that can't send them (the free month, or no verified mail domain) earns no referral credit by email until it can (see Set up email). Sign-ups by number are unaffected. The friend's own side never waits: they start higher or get straight in when they join. Friends who counted before confirmation was required stay counted.

Set up referrals

GET `/projects/:id/referrals` Needs analytics

Get the referral settings.

Show 8 details

Returns enabled, hold, sharer, friend, milestones, deal, link and link_example.
deal: what both sides get, in plain words, as the founder's screen says it.
link: the referral link on the founder's own site, with {code} where a person's code goes, or null.
link_example: a person's link as it reads now. Without link, it's the project's site with ?ref=<code>.
hold: whether friends who look gamed wait for review before they count (see Review flagged friends). On for new projects.
sharer: what the person who shares gets.
- gets: nothing, move_up (up the line by places_per_friend for each friend), access (once friends_for_access friends join) or reward (something the founder gives).
- places_per_friend: at least 1. The default is 1.
- friends_for_access: 1 to 100. The default is 3.
friend: what the friend who joins gets.
- gets: nothing, start_higher (join places above the end of the line), access (straight in, see Let friends straight in) or reward (the founder gives them reward).
- places: 1 to 1000. The default is 10.
- reward: up to 140 characters, or null. Friends see nothing until it's written.
- access_limit: how many friends of one person get straight in. 1 to 1000. The default is 10.
- access_from: whose links let friends straight in. anyone on the list (the default) or only people let_in.
milestones: extra rewards for the sharer, fewest friends first. Each has friends (1 to 1000) and reward (up to 140 characters). Up to 10, each for a different number of friends. After joining, a person sees how many more friends they need for the next one.

GET /projects/:id/referrals

curl https://app.hunchwire.com/projects/:id/referrals \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN"

import os, requests

r = requests.get(
    "https://app.hunchwire.com/projects/:id/referrals",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/referrals", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
  },
})
const data = await res.json()

PATCH `/projects/:id/referrals` Needs manage

Change the referral settings.

Show 6 details

Send any part. What you leave out stays.
milestones replaces the whole list. Send [] for none.
Before turning referrals on, ask the founder what each side gets. People see it the moment they join.
Turning referrals off hides places, links and lines from visitors. It doesn't change the line, so turning them on again shows the same places.
When people share a page on the founder's own site, send "link": "https://yourapp.com/r/{code}". It must be a full address containing {code}. Send "" to clear it.
The founder's own product reads each person's place, friends and link from the API (see API).

PATCH /projects/:id/referrals

curl -X PATCH https://app.hunchwire.com/projects/:id/referrals \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"referrals": {"enabled": true, "sharer": {"gets": "move_up", "places_per_friend": 1}, "friend": {"gets": "reward", "reward": "20% off the first year"}, "milestones": [{"friends": 3, "reward": "Early access"}, {"friends": 10, "reward": "A free year"}]}}'

import os, requests

r = requests.patch(
    "https://app.hunchwire.com/projects/:id/referrals",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
    json={"referrals": {"enabled": True, "sharer": {"gets": "move_up", "places_per_friend": 1}, "friend": {"gets": "reward", "reward": "20% off the first year"}, "milestones": [{"friends": 3, "reward": "Early access"}, {"friends": 10, "reward": "A free year"}]}},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/referrals", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"referrals": {"enabled": true, "sharer": {"gets": "move_up", "places_per_friend": 1}, "friend": {"gets": "reward", "reward": "20% off the first year"}, "milestones": [{"friends": 3, "reward": "Early access"}, {"friends": 10, "reward": "A free year"}]}}),
})
const data = await res.json()

The share kit is what people get to share after joining.

Get the share kit.

Details

headline: shown on each person's share image. The default is the project's name.
posts: one per channel (x, linkedin, reddit, email). A post is the founder's words, or a default until they write one. An empty post means no button for that channel.

GET /projects/:id/setup/referrals/share-kit

curl https://app.hunchwire.com/projects/:id/setup/referrals/share-kit \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN"

import os, requests

r = requests.get(
    "https://app.hunchwire.com/projects/:id/setup/referrals/share-kit",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/setup/referrals/share-kit", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
  },
})
const data = await res.json()

Change the share kit.

Show 5 details

Send any part. What you leave out stays.
{link} is the person's link. {place} is their place in line. It's empty when the line doesn't move, so don't use it then.
A post without {link} gets it at the end.
Up to 500 characters a post, and 80 for the headline.
Write posts the way someone would say it to a friend. The defaults are plain on purpose.

PATCH /projects/:id/setup/referrals/share-kit

curl -X PATCH https://app.hunchwire.com/projects/:id/setup/referrals/share-kit \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_kit": {"headline": "Habits that stick, together.", "posts": {"x": "I'm #{place} in line for Loop. Skip the line with my link: {link}", "reddit": ""}}}'

import os, requests

r = requests.patch(
    "https://app.hunchwire.com/projects/:id/setup/referrals/share-kit",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
    json={"share_kit": {"headline": "Habits that stick, together.", "posts": {"x": "I'm #{place} in line for Loop. Skip the line with my link: {link}", "reddit": ""}}},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/setup/referrals/share-kit", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"share_kit": {"headline": "Habits that stick, together.", "posts": {"x": "I'm #{place} in line for Loop. Skip the line with my link: {link}", "reddit": ""}}}),
})
const data = await res.json()

Give rewards

GET `/projects/:id/people/rewards?page=1` Needs emails

List rewards earned, newest first, 50 a page.

Show 7 details

Shows who is owed what, and whether the founder gave it.
Returns total (all of them), page, per_page and rewards. Ask for the next page while page × per_page < total.
.csv returns a file of every reward, unpaged.
The list is empty while referrals are off.
Each item in rewards has email, reward (milestone:3, access or friend), label (as the screen says it, like "3 friends · Early access"), reached_at, given, given_at and given_by (who marked it, automatic when a friend's link let them in, or null).
A milestone is reached when the person's Nth friend joins. access is reached when a sharer who gets access unlocks it. friend is reached when someone joins through a link and friends get access or a reward.
Give access with an invite (POST /projects/:id/invites, see Let people in). Once the person has one, the reward reads as given. A friend let in through a link has one already.

GET /projects/:id/people/rewards

curl https://app.hunchwire.com/projects/:id/people/rewards?page=1 \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN"

import os, requests

r = requests.get(
    "https://app.hunchwire.com/projects/:id/people/rewards?page=1",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/people/rewards?page=1", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
  },
})
const data = await res.json()

POST `/projects/:id/people/rewards` Needs manage and emails

with email, reward and given (true, the default, or false): mark a reward given, or undo that.

Details

Mark it once the founder has sent it. Only do this when the founder says they gave it.
Returns the reward. 404 for a reward that isn't earned.

POST /projects/:id/people/rewards

curl -X POST https://app.hunchwire.com/projects/:id/people/rewards \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN"

import os, requests

r = requests.post(
    "https://app.hunchwire.com/projects/:id/people/rewards",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/people/rewards", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
  },
})
const data = await res.json()

Let friends straight in

When friends get access, joining through a friend's link is the invite.

The friend gets an invite the moment they sign up, with via referral. Hunchwire sends no confirmation email: the founder's own sign-up checks the address.
From the form, they go straight to the Let people in address with a token. From the API, the sign-up's answer carries the invite, so your product can welcome them in its first reply.
A friend who signs up by number gets access at sign-up, with no hand-off: there's no web sign-up by number. Check access when they first text you (POST /v1/people or GET /v1/people?phone=). That first text proves the number.
On a first sign-up, it applies when the friend counts: not held for review and not rejected. A removed person's link lets no one in.
Someone already on the list who signs up again through someone else's link is let in the same way, once they confirm. Their place and referrer don't change.
- The link's owner gets credit for them, as for a friend who joined through it. They move up, and it counts toward milestones and access. It counts from the moment the sign-up is confirmed. Their referrer keeps their own credit.
- A link that changes nothing earns no one anything. That's someone already in, or a link at its access_limit.
- By email, Hunchwire sends a confirmation whose link carries the friend's code. Clicking it lets them in if the link still has room. From the form, it then sends them to the Let people in address. The project must be able to email its people (see Confirm sign-ups).
- By number, send the sign-up again with confirmed and the ref. The answer carries the invite.
- With hold on, a sign-up again from a browser the link's owner signed up from isn't let in.
- A removed person who signs up again through a link comes back when they click, then is let in if the link allows.
With access_from let_in, only the links of people the founder let in let friends in. Let in means the person has an invite, of any kind and in any state. A friend let in through a link counts too. Other people's friends still count for them but wait on the list, and the form promises nothing.
Each person's link lets in up to access_limit people. It counts everyone let in through it, at sign-up or at confirmation. After that, friends still count for them but wait on the list, and the form stops promising to skip the wait.
The form needs a Let people in address to send an email friend somewhere. Without one, they wait on the list and the founder invites them. The API needs no address.
A friend approved later in Review flagged friends isn't let in by that. Invite them from People › Rewards earned.

Review flagged friends

While hold is on, some friends wait for review. A friend waits when they signed up from a browser their referrer signed up from. Friends also wait when two or more of one referrer's friends signed up from one browser.

Until approved, they don't count for their referrer, or for their own reward.

GET `/projects/:id/people/referrals/flagged?page=1` Needs emails

List friends held for review, newest first, 50 groups a page.

Details

Returns total, page, per_page and flagged.
Each item in flagged has referrer, friends (their emails; several from one browser are decided together), reason (same_browser or one_browser), why (as the screen says it) and joined_at.

GET /projects/:id/people/referrals/flagged

curl https://app.hunchwire.com/projects/:id/people/referrals/flagged?page=1 \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN"

import os, requests

r = requests.get(
    "https://app.hunchwire.com/projects/:id/people/referrals/flagged?page=1",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/people/referrals/flagged?page=1", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
  },
})
const data = await res.json()

POST `/projects/:id/people/referrals/flagged` Needs manage and emails

with emails (a list) and decision (approved or rejected): approve or reject held friends.

Details

Approved friends count at once. Rejected ones never count.
Only do this when the founder decided. Never approve or reject on your own judgement.
Returns decision and friends. 404 when none of the emails are waiting.

POST /projects/:id/people/referrals/flagged

curl -X POST https://app.hunchwire.com/projects/:id/people/referrals/flagged \
  -H "Authorization: Bearer $HUNCHWIRE_TOKEN"

import os, requests

r = requests.post(
    "https://app.hunchwire.com/projects/:id/people/referrals/flagged",
    headers={"Authorization": f"Bearer {os.environ['HUNCHWIRE_TOKEN']}"},
)
r.json()

const res = await fetch("https://app.hunchwire.com/projects/:id/people/referrals/flagged", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HUNCHWIRE_TOKEN}`,
  },
})
const data = await res.json()

How the line works

A person's place is their join position, minus:

places_per_friend × friends, when sharers move up.
The friend's places, when friends start higher.
Places the founder or an agent moved them by hand (moved, in People).

The lowest number comes first. Removed people have no place. Ties go to whoever has more friends, then to a friend who started higher, then to whoever joined first.

When neither side moves anyone, the line is join order and visitors see no place.

A friend is someone whose first sign-up came through the link. A sharer's own sign-ups, and other spellings of their email, never count.

Made from skill.md, the file agents read. Add .md to any page's address for its Markdown.

Referrals

Referrals

Set up referrals

GET /projects/:id/referrals Needs analytics

PATCH /projects/:id/referrals Needs manage

Edit the share kit

GET /projects/:id/setup/referrals/share-kit Needs analytics

PATCH /projects/:id/setup/referrals/share-kit Needs manage

Give rewards

GET /projects/:id/people/rewards?page=1 Needs emails

POST /projects/:id/people/rewards Needs manage and emails

Let friends straight in

Review flagged friends

GET /projects/:id/people/referrals/flagged?page=1 Needs emails

POST /projects/:id/people/referrals/flagged Needs manage and emails

How the line works

GET `/projects/:id/referrals` Needs analytics

PATCH `/projects/:id/referrals` Needs manage

GET `/projects/:id/setup/referrals/share-kit` Needs analytics

PATCH `/projects/:id/setup/referrals/share-kit` Needs manage

GET `/projects/:id/people/rewards?page=1` Needs emails

POST `/projects/:id/people/rewards` Needs manage and emails

GET `/projects/:id/people/referrals/flagged?page=1` Needs emails

POST `/projects/:id/people/referrals/flagged` Needs manage and emails