# GET /referrals/requests

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

List referral request lifecycle rows (sent -> viewed -> submitted -> expired). Filter by status or contact_id. Useful for "who has been asked but not yet submitted".

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `status` | query | string | no | sent \| viewed \| submitted \| expired |
| `contact_id` | query | string | no | UUID. Filter to requests sent TO this contact. |
| `limit` | query | number | no | Max records (default 20, max 100). |
| `after` | query | string | no | Pagination cursor. |

## Request example

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

## Response example

```json
{
  "data": [
    {
      "id": "ccdd1234-abcd-1234-abcd-abcdef123456",
      "company_id": "ebeff86e-7b09-4e49-96db-f711d69d2d57",
      "contact_id": "1068084c-f975-4bb8-be1b-4f0a2f0843be",
      "deal_id": null,
      "recipient_email": "referrer@example.com",
      "recipient_name": "Jane Smith",
      "status": "sent",
      "sent_at": "2026-05-16T10:00:00.000Z",
      "viewed_at": null,
      "submitted_at": null,
      "referral_id": null,
      "expires_at": "2026-06-15T10:00:00.000Z",
      "created_at": "2026-05-16T10: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`