# GET /referrals

**Resource:** [Referrals](./referrals.md)  
**Scopes:** `referrals:read`  
**Write operation:** no

List referrals for the workspace. Filter by status, referrer_contact_id, referred_contact_id, or category. Returns the full referral chain including category and notes.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `status` | query | string | no | pending \| accepted \| converted \| declined |
| `referrer_contact_id` | query | string | no | UUID. Filter to referrals made BY this contact. |
| `referred_contact_id` | query | string | no | UUID. Filter to the referral that produced this contact. |
| `category` | query | string | no | Filter by workspace-defined category (e.g. "CT", "MRI", "Mortgage"). |
| `limit` | query | number | no | Max records to return (default 20, max 100). |
| `after` | query | string | no | Cursor for pagination (from previous response pagination.next_cursor). |

## Request example

```bash
curl "https://ucqwijexmjctglmrxlej.supabase.co/functions/v1/api/v1/referrals?category=CT&status=pending" \
  -H "Authorization: Bearer tp_live_..."
```

## Response example

```json
{
  "data": [
    {
      "id": "f2788884-aaaa-bbbb-cccc-111111111111",
      "company_id": "ebeff86e-7b09-4e49-96db-f711d69d2d57",
      "referrer_contact_id": "1068084c-f975-4bb8-be1b-4f0a2f0843be",
      "referred_contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "referred_deal_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "source": "form",
      "status": "pending",
      "category": "CT",
      "notes": null,
      "converted_at": null,
      "created_at": "2026-05-01T09:00:00.000Z",
      "updated_at": "2026-05-01T09:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "has_more": false,
    "next_cursor": null
  },
  "meta": { "credits_remaining": 4500 }
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`