List a contact's referrals

Everyone this person brought in, with the credit state of each referral and the reason when credit was skipped.

Updated ·3 min read
GET/v1/contacts/{contact}/referrals

Requires the contacts:read scope.

Who this contact brought in. Each entry is a full contact object, not a separate referral record. The referral state lives on the contact's own referral.state.

The list takes the usual limit, starting_after and ending_before parameters and is ordered newest first. See pagination.

Referral states#

referral.state describes this contact's own inbound referral, meaning how the person who brought them in was treated.

State Meaning
credited Counted. The referrer moved up
pending_verification Referred, not credited yet: usually the new signup has not verified
pending:{reason} Referred and held, to be judged again later. The reason follows the colon
skipped:{reason} Referred, and credit was deliberately not given. The reason follows the colon
null Nobody referred this person

Every entry in this list was referred by the contact you asked about, so null does not appear here. It does appear on contacts read through other endpoints.

Pending reasons#

Reason Meaning
pending:held_velocity The referrer is past the hourly limit. It counts once their last hour has room
pending:held_relay_velocity The same, for a signup sent through a site builder's servers
pending:held_device Another signup came from the same device moments ago. It is decided about two hours after they signed up

Skip reasons#

Reason Meaning
skipped:self_referral They used their own code
skipped:per_ip_cap Too many signups credited to one IP address already
skipped:device_cluster Several signups came from the same device in a short time
skipped:velocity Far more arrived in an hour than real sharing brings
skipped:missing_referrer The code did not resolve to a contact on this project
skipped:already_credited That credit had been counted once already

Treat this as an open set: match on the skipped: prefix rather than the full string, so a reason added later reads as skipped rather than as unknown.

pending_verification is the answer to "my friend joined but my count did not go up", the single most common referral support question, and it usually resolves itself.

See how referrals work for why credit waits for verification.

Next#

Was this page helpful?
curl "https://api.getlaunchlist.com/v1/contacts/con_4mKp9Wq2Rx/referrals" \\
  -H "Authorization: Bearer llk_live_8xKq3Rp9Wm2Nz7Vt6yL1cG5dH0jA4sE8uNqB2fXk"
{
  "object": "list",
  "url": "/v1/contacts/con_4mKp9Wq2Rx/referrals",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "con_9Rt3Xm7Kp2",
      "livemode": true,
      "project": "prj_7Qk2mN4pR8",
      "identifier": "grace@hopper.dev",
      "identifier_type": "email",
      "email": "grace@hopper.dev",
      "external_id": null,
      "attributes": {},
      "status": "subscribed",
      "stage": "waitlist",
      "deliverability": null,
      "trust_tier": "verified",
      "position": 1321,
      "referral": {
        "code": "GRC4K1",
        "url": "https://acme.launchlist.page?ref=GRC4K1",
        "count": 0,
        "referred_by": "con_4mKp9Wq2Rx",
        "state": "credited"
      },
      "unsubscribed": false,
      "locked": false,
      "verified_at": "2026-07-29T10:20:41+00:00",
      "opt_in_confirmed_at": "2026-07-29T10:20:41+00:00",
      "consent": "signup",
      "consented_at": "2026-07-29T10:14:02+00:00",
      "unsubscribed_by": null,
      "unsubscribed_at": null,
      "created_at": "2026-07-29T10:14:02+00:00",
      "url": "/v1/contacts/con_9Rt3Xm7Kp2"
    }
  ]
}