> ## Documentation Index > Fetch the complete documentation index at: https://www.referly.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Referral(s) > 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. ## OpenAPI ````yaml GET /referrals openapi: 3.0.1 info: title: Referly API description: >- REST API for managing affiliates, referrals, sales, affiliate links, coupons and promotional codes in your Referly affiliate program. Every request must send `Authorization: Bearer `. The token is scoped to a single affiliate program, so no program ID is ever required in the request — every read and write is automatically limited to that program. Requests are rate limited per token, per endpoint and per method. version: 1.0.0 servers: - url: https://www.referly.so/api/v1 security: - bearerAuth: [] paths: /referrals: get: summary: Get referral(s) description: >- 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. parameters: - name: id in: query description: >- The referral's UUID. If no referral has that ID, the value is retried as a referral email address. Returns a single referral. schema: type: string - name: affiliateId in: query description: Return every referral belonging to this affiliate UUID. schema: type: string format: uuid - name: affiliateEmail in: query description: >- Return every referral belonging to the affiliate with this email address. schema: type: string format: email - name: externalId in: query description: >- Return every referral whose `referredUserExternalId` matches — the ID you gave the referred user in your own database. schema: type: string responses: '200': description: >- A single referral when filtering by `id` (`null` if no match), otherwise an array. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Referral' - type: array items: $ref: '#/components/schemas/Referral' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/ProgramNotFound' '429': $ref: '#/components/responses/RateLimited' components: schemas: Referral: type: object properties: id: type: string format: uuid description: The referral ID affiliateId: type: string format: uuid nullable: true description: The affiliate credited with this referral affiliateProgramId: type: string format: uuid nullable: true description: The affiliate program this referral belongs to affiliateLinkId: type: string format: uuid nullable: true description: The affiliate link the referral came through commissionPlanId: type: string format: uuid nullable: true description: The commission plan applied to this referral name: type: string nullable: true description: Name of the referred user email: type: string format: email nullable: true description: Email of the referred user referredUserExternalId: type: string description: >- The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID. plan: type: string nullable: true description: Plan the referred user is on. Defaults to `N/A` when not supplied. subscriptionStatus: type: string enum: - ACTIVE - SUBMITTED - DECLINED nullable: true description: >- Status of the referral. Referrals created through this API are always `ACTIVE`. submissionType: type: string enum: - MANUAL - AUTOMATIC nullable: true description: Whether the referral was submitted by hand or captured automatically referralMedium: type: string enum: - COUPON - LINK nullable: true description: How the referral was tracked source: type: string enum: - UNKNOWN - API - INTEGRATION - MANUAL - IMPORTED - AFFILIATE_SUBMITTED description: >- Where the referral came from. Referrals created through this API have `API`. totalRevenue: type: number format: float description: Total revenue attributed to this referral totalCommission: type: number format: float description: Total commission generated by this referral initialLandingPage: type: string nullable: true description: The first page the referred user landed on notes: type: string nullable: true description: Free-text notes on the referral metadata: type: object nullable: true description: Arbitrary JSON you can attach to the referral createdAt: type: string format: date-time description: When the referral was created Error: type: object properties: error: type: string description: Human readable description of what went wrong responses: Unauthorized: description: >- The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: API access is not enabled for this account. content: application/json: schema: $ref: '#/components/schemas/Error' ProgramNotFound: description: The affiliate program this token belongs to no longer exists. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests for this token on this endpoint. Please slow down. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````