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

# List Referrals

> Retrieve a list of all referrals (signups) from your programs

Retrieve a list of all referrals (signups) from your programs. This endpoint supports filtering by program, student, and status, making it easy to track conversions and manage your referral pipeline.

## Overview

The List Referrals endpoint returns a paginated list of all referrals created through your ambassador programs. Use this endpoint to:

* Track all signups from referral links
* Filter referrals by program or ambassador
* Monitor referral status (pending, converted, verified, rejected)
* Build analytics dashboards
* Export referral data for reporting

## Authentication

This endpoint requires authentication using a Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer sk_your_secret_key_here
```

## Query Parameters

<ParamField body="programId" type="string" required={false}>
  Filter results to only include referrals from a specific program. Useful when analyzing performance of individual programs.

  **Example:** `programId=prog_123abc`
</ParamField>

<ParamField body="studentId" type="string" required={false}>
  Filter results to only include referrals from a specific student ambassador. Use this to see all referrals generated by a particular ambassador.

  **Example:** `studentId=user_123abc`
</ParamField>

<ParamField body="status" type="string" required={false}>
  Filter referrals by their current status. Valid values are:

  * `pending` - Referral created but not yet converted
  * `converted` - Referral has converted (made a purchase/subscription)
  * `verified` - Referral has been verified
  * `rejected` - Referral was rejected

  **Example:** `status=converted` returns only converted referrals
</ParamField>

<ParamField body="limit" type="integer" default="50" required={false}>
  Maximum number of results to return per page. Default is 50, maximum is typically 100.

  **Example:** `limit=25`
</ParamField>

<ParamField body="offset" type="integer" default="0" required={false}>
  Number of results to skip before starting to return results. Use for pagination.

  **Example:** `offset=50` skips the first 50 results
</ParamField>

## Request Example

<RequestExample>
  ```bash theme={null}
  # Get all referrals
  curl -X GET "https://vantio.app/api/v1/referrals" \
    -H "Authorization: Bearer sk_your_secret_key_here"

  # Get converted referrals from a specific program
  curl -X GET "https://vantio.app/api/v1/referrals?programId=prog_123abc&status=converted&limit=100" \
    -H "Authorization: Bearer sk_your_secret_key_here"

  # Get referrals from a specific ambassador
  curl -X GET "https://vantio.app/api/v1/referrals?studentId=user_123abc" \
    -H "Authorization: Bearer sk_your_secret_key_here"
  ```
</RequestExample>

## Response

The API returns a JSON object containing an array of referral objects:

<ResponseField name="referrals" type="array" required>
  Array of referral objects, each containing information about a referral signup.
</ResponseField>

Each referral object contains:

<ResponseField name="id" type="string" required>
  Unique identifier for the referral.
</ResponseField>

<ResponseField name="impression_id" type="string" required>
  ID of the impression (QR scan) that led to this referral.
</ResponseField>

<ResponseField name="first_name" type="string" required>
  First name of the referred person.
</ResponseField>

<ResponseField name="last_name" type="string" required>
  Last name of the referred person.
</ResponseField>

<ResponseField name="email" type="string" required>
  Email address of the referred person.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current status of the referral: `pending`, `converted`, `verified`, or `rejected`.
</ResponseField>

<ResponseField name="program_id" type="string" required>
  ID of the program this referral belongs to.
</ResponseField>

<ResponseField name="student_id" type="string" required>
  ID of the student ambassador who generated this referral.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the referral was created.
</ResponseField>

<ResponseField name="verified_at" type="string">
  ISO 8601 timestamp of when the referral was verified, if applicable.
</ResponseField>

## Response Example

<ResponseExample>
  ```json theme={null}
  {
    "referrals": [
      {
        "id": "ref_123abc",
        "impression_id": "imp_456def",
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice.johnson@example.com",
        "status": "converted",
        "program_id": "prog_123abc",
        "student_id": "user_123abc",
        "created_at": "2024-01-15T10:30:00Z",
        "verified_at": "2024-01-16T14:20:00Z",
        "metadata": {
          "source": "poster_qr_code",
          "location": "campus_center"
        }
      },
      {
        "id": "ref_789ghi",
        "impression_id": "imp_012jkl",
        "first_name": "Bob",
        "last_name": "Williams",
        "email": "bob.williams@example.com",
        "status": "pending",
        "program_id": "prog_123abc",
        "student_id": "user_456def",
        "created_at": "2024-01-17T09:15:00Z",
        "verified_at": null
      }
    ]
  }
  ```
</ResponseExample>

## Use Cases

### Building a Referral Dashboard

Fetch all referrals and display them in a dashboard with filtering:

```javascript theme={null}
async function fetchReferrals(filters = {}) {
  const params = new URLSearchParams();
  
  if (filters.programId) params.append('programId', filters.programId);
  if (filters.studentId) params.append('studentId', filters.studentId);
  if (filters.status) params.append('status', filters.status);
  if (filters.limit) params.append('limit', filters.limit);
  if (filters.offset) params.append('offset', filters.offset);
  
  const response = await fetch(
    `https://vantio.app/api/v1/referrals?${params.toString()}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  return await response.json();
}
```

### Tracking Conversion Rates

Calculate conversion rates by status:

```javascript theme={null}
async function getConversionStats(programId) {
  const allReferrals = await fetchReferrals({ programId, limit: 1000 });
  const converted = await fetchReferrals({ programId, status: 'converted', limit: 1000 });
  
  const total = allReferrals.referrals.length;
  const convertedCount = converted.referrals.length;
  const conversionRate = (convertedCount / total) * 100;
  
  return {
    total,
    converted: convertedCount,
    conversionRate: conversionRate.toFixed(2) + '%'
  };
}
```

### Exporting Referral Data

Fetch all referrals for export:

```javascript theme={null}
async function exportAllReferrals(programId) {
  let allReferrals = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://vantio.app/api/v1/referrals?programId=${programId}&limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    );
    
    const data = await response.json();
    allReferrals = [...allReferrals, ...data.referrals];
    
    hasMore = data.referrals.length === limit;
    offset += limit;
  }
  
  return allReferrals;
}
```

## Best Practices

1. **Use filters wisely** - Combine filters to narrow down results and reduce response size
2. **Implement pagination** - Always use `limit` and `offset` for large datasets
3. **Cache frequently accessed data** - Referral lists don't change as frequently as other data
4. **Monitor status changes** - Set up webhooks or polling to track status updates
5. **Handle empty results** - Always check if the referrals array is empty

## Error Responses

<ResponseField name="401" type="object">
  **Unauthorized** - Invalid or missing API key

  ```json theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseField>

## Rate Limits

This endpoint is subject to rate limiting. Check response headers for rate limit information.


## OpenAPI

````yaml GET /api/v1/referrals
openapi: 3.0.0
info:
  title: Vantio API
  version: 1.0.0
  description: >-
    Public v1 API. Authenticate using your secret key in the Authorization
    header: "Bearer sk_...".
servers:
  - url: http://localhost:3000
security:
  - bearerAuth: []
tags:
  - name: Users
    description: Student directory within your programs
  - name: Referrals
    description: Signups and conversions
  - name: Posters
    description: Ambassador posters and placements
  - name: Impressions
    description: QR scans and related activity
  - name: Earnings
    description: Earnings from referrals
paths:
  /api/v1/referrals:
    get:
      tags:
        - Referrals
      summary: List referrals
      description: Retrieve a list of all referrals (signups) from your programs
      parameters:
        - in: query
          name: programId
          schema:
            type: string
          description: Filter by program ID
        - in: query
          name: studentId
          schema:
            type: string
          description: Filter by student (ambassador) ID
        - in: query
          name: status
          schema:
            type: string
            enum:
              - pending
              - converted
              - verified
              - rejected
          description: Filter by referral status
        - in: query
          name: limit
          schema:
            type: integer
            default: 50
          description: Maximum number of results to return
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
          description: Number of results to skip
      responses:
        '200':
          description: List of referrals
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - Invalid or missing API key
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````