> ## Documentation Index
> Fetch the complete documentation index at: https://developers.referly.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Referral(s)

> Returns a list of referrals based on the affiliate program, filtered by optional referral ID, affiliate ID, affiliate email, or external ID



## OpenAPI

````yaml GET /referrals
openapi: 3.0.1
info:
  title: Referly API
  description: API for managing affiliates, referrals, and sales for SaaS businesses
  version: 1.0.0
servers:
  - url: https://www.referly.so/api/v1
security:
  - bearerAuth: []
paths:
  /referrals:
    get:
      summary: Get all referrals or by ID/email/externalId
      description: >-
        Returns a list of referrals based on the affiliate program, filtered by
        optional referral ID, affiliate ID, affiliate email, or external ID
      parameters:
        - name: id
          in: query
          description: The ID of the referral to retrieve
          schema:
            type: string
            format: uuid
        - name: affiliateId
          in: query
          description: The affiliate ID associated with the referral
          schema:
            type: string
            format: uuid
        - name: affiliateEmail
          in: query
          description: The email of the affiliate associated with the referral
          schema:
            type: string
            format: email
        - name: externalId
          in: query
          description: The external ID of the referred user
          schema:
            type: string
      responses:
        '200':
          description: A list of referrals or a single referral
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Referral'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Referral:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The referral ID
        affiliateId:
          type: string
          format: uuid
          description: The affiliate ID associated with the referral
        name:
          type: string
          description: Name of the referred user
        email:
          type: string
          format: email
          description: Email of the referred user
        referredUserExternalId:
          type: string
          description: >-
            The external ID of the referred user. This will be an ID you
            actively maintain that identifies the user on your server (for
            example, the User ID in your database, or Stripe Customer ID)
        plan:
          type: string
          description: The plan associated with the referred user
        status:
          type: string
          description: Status of the referral (active/inactive)
    Error:
      type: object
      properties:
        error:
          type: integer
          description: Error code
        message:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````