# POST /referrals

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

Manually log a referral (verbal/ad-hoc). source defaults to "manual". For form-driven flows use POST /referrals/request. For automation-driven attribution configure the attribute_referral automation action.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `referrer_contact_id` | body | string | yes | UUID of the contact who made the referral. |
| `referred_contact_id` | body | string | no | UUID of the referred person if already in the CRM. |
| `referred_deal_id` | body | string | no | UUID of the opportunity created from this referral. |
| `source` | body | string | no | form \| manual \| api. Defaults to "manual". |
| `status` | body | string | no | pending \| accepted \| converted \| declined. Defaults to "pending". |
| `category` | body | string | no | Workspace-defined category (e.g. "CT", "MRI", "Mortgage"). Configure the picklist via PATCH /v1/company/crm-settings with referral_categories. |
| `notes` | body | string | no | Free-text notes about this referral. |

## Request example

```bash
curl -X POST "https://ucqwijexmjctglmrxlej.supabase.co/functions/v1/api/v1/referrals" \
  -H "Authorization: Bearer tp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "referrer_contact_id": "1068084c-f975-4bb8-be1b-4f0a2f0843be",
    "category": "MRI",
    "notes": "Met at the networking event last Tuesday"
  }'
```

## Response example

```json
{
  "data": {
    "id": "8aa0c05e-d0b2-49b3-b6e8-2da112254c63",
    "company_id": "ebeff86e-7b09-4e49-96db-f711d69d2d57",
    "referrer_contact_id": "1068084c-f975-4bb8-be1b-4f0a2f0843be",
    "referred_contact_id": null,
    "referred_deal_id": null,
    "source": "manual",
    "status": "pending",
    "category": "MRI",
    "notes": "Met at the networking event last Tuesday",
    "converted_at": null,
    "created_at": "2026-05-16T10:00:00.000Z",
    "updated_at": "2026-05-16T10:00:00.000Z"
  },
  "meta": { "credits_remaining": 4499 }
}
```

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