LaunchListBeta

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 ·2 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, but credit has not been attempted yet, usually because the new signup has not verified
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.

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:velocity Credits arrived too fast to come from real sharing
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"
    }
  ]
}