# POST /referrals/request

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

Send a tracked referral-request email to a known contact. The recipient lands on a public page and submits a friend's details -- the platform auto-creates a contact + opportunity + referral row on submit. Returns request_id, token, and public_url.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `contact_id` | body | string | yes | UUID of the referrer contact (the person being asked to refer someone). |
| `deal_id` | body | string | no | Optional opportunity context for variable resolution in the email template. |
| `subject_override` | body | string | no | Override the email subject line. Supports {{contact.first_name}} tokens. |
| `intro_html` | body | string | no | Override the intro paragraph (raw HTML). Supports template tokens. |
| `how_it_works_html` | body | string | no | Override the "how it works" card HTML. |
| `expires_in_days` | body | number | no | Days until the public link expires. Default 30. |

## Request example

```bash
curl -X POST "https://ucqwijexmjctglmrxlej.supabase.co/functions/v1/api/v1/referrals/request" \
  -H "Authorization: Bearer tp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"contact_id": "1068084c-f975-4bb8-be1b-4f0a2f0843be", "expires_in_days": 30}'
```

## Response example

```json
{
  "data": {
    "request_id": "ccdd1234-abcd-1234-abcd-abcdef123456",
    "token": "abc123def456",
    "public_url": "https://app.trustpager.com/refer/abc123def456",
    "expires_at": "2026-06-15T10:00:00.000Z",
    "email_sent": true
  },
  "meta": { "credits_remaining": 4496 }
}
```

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