---
title: "Get referral(s)"
method: GET
path: "/referrals"
---

# Get referral(s)

`GET /referrals`

Returns referrals for your program. Supply `id` to fetch one referral, `affiliateId` / `affiliateEmail` to list everything a given affiliate referred, or `externalId` to look a referral up by the ID it has in your own system. With no parameters, every referral in the program is returned.

A referral that does not exist comes back as `null` with a 200, not a 404.

## Query parameters

- `id` string
- `affiliateId` string, uuid
- `affiliateEmail` string, email
- `externalId` string

## Response `200`

A single referral when filtering by `id` (`null` if no match), otherwise an array.

- union
  - Referral
    - `id` string, uuid — The referral ID
    - `affiliateId` string, uuid, nullable — The affiliate credited with this referral
    - `affiliateProgramId` string, uuid, nullable — The affiliate program this referral belongs to
    - `affiliateLinkId` string, uuid, nullable — The affiliate link the referral came through
    - `commissionPlanId` string, uuid, nullable — The commission plan applied to this referral
    - `name` string, nullable — Name of the referred user
    - `email` string, email, nullable — Email of the referred user
    - `referredUserExternalId` string — The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.
    - `plan` string, nullable — Plan the referred user is on. Defaults to `N/A` when not supplied.
    - `subscriptionStatus` 'ACTIVE' | 'SUBMITTED' | 'DECLINED', nullable — Status of the referral. Referrals created through this API are always `ACTIVE`.
    - `submissionType` 'MANUAL' | 'AUTOMATIC', nullable — Whether the referral was submitted by hand or captured automatically
    - `referralMedium` 'COUPON' | 'LINK', nullable — How the referral was tracked
    - `source` 'UNKNOWN' | 'API' | 'INTEGRATION' | 'MANUAL' | 'IMPORTED' | 'AFFILIATE_SUBMITTED' — Where the referral came from. Referrals created through this API have `API`.
    - `totalRevenue` number, float — Total revenue attributed to this referral
    - `totalCommission` number, float — Total commission generated by this referral
    - `initialLandingPage` string, nullable — The first page the referred user landed on
    - `notes` string, nullable — Free-text notes on the referral
    - `metadata` object, nullable — Arbitrary JSON you can attach to the referral
    - `createdAt` string, date-time — When the referral was created
  - Referral[]
    - `id` string, uuid — The referral ID
    - `affiliateId` string, uuid, nullable — The affiliate credited with this referral
    - `affiliateProgramId` string, uuid, nullable — The affiliate program this referral belongs to
    - `affiliateLinkId` string, uuid, nullable — The affiliate link the referral came through
    - `commissionPlanId` string, uuid, nullable — The commission plan applied to this referral
    - `name` string, nullable — Name of the referred user
    - `email` string, email, nullable — Email of the referred user
    - `referredUserExternalId` string — The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.
    - `plan` string, nullable — Plan the referred user is on. Defaults to `N/A` when not supplied.
    - `subscriptionStatus` 'ACTIVE' | 'SUBMITTED' | 'DECLINED', nullable — Status of the referral. Referrals created through this API are always `ACTIVE`.
    - `submissionType` 'MANUAL' | 'AUTOMATIC', nullable — Whether the referral was submitted by hand or captured automatically
    - `referralMedium` 'COUPON' | 'LINK', nullable — How the referral was tracked
    - `source` 'UNKNOWN' | 'API' | 'INTEGRATION' | 'MANUAL' | 'IMPORTED' | 'AFFILIATE_SUBMITTED' — Where the referral came from. Referrals created through this API have `API`.
    - `totalRevenue` number, float — Total revenue attributed to this referral
    - `totalCommission` number, float — Total commission generated by this referral
    - `initialLandingPage` string, nullable — The first page the referred user landed on
    - `notes` string, nullable — Free-text notes on the referral
    - `metadata` object, nullable — Arbitrary JSON you can attach to the referral
    - `createdAt` string, date-time — When the referral was created

## Other responses

- `401` — The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid.
- `403` — API access is not enabled for this account.
- `404` — The affiliate program this token belongs to no longer exists.
- `429` — Too many requests for this token on this endpoint. Please slow down.

---

[API](https://skmtc.net/referly/apis/referly-api.md) · [All operations](https://skmtc.net/referly/apis/referly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/referly/referly-api/versions/0f506d61b9c3/schema)