# GET /opportunities

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

List all opportunities with cursor-based pagination. Supports search, status, contact, company, pipeline, stage, and date filters. Always includes pipeline placements. Response always includes read-only referral attribution fields: primary_referrer_contact_id (UUID of the most-recent referrer, maintained by a Postgres trigger) and primary_referrer_category (workspace category string). Use expand=referrer to inline the full referrer contact object. When using expand=products, payment_status on each product is stripped unless the caller has invoices:read scope. Legacy alias: GET /deals (same response shape).

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `search` | query | string | no | Search by opportunity name, contact name/email/phone, or company name/email/phone |
| `status` | query | string | no | Filter by status (open, won, lost) |
| `contact_id` | query | uuid | no | Filter by primary contact |
| `customer_id` | query | uuid | no | Filter by company (formerly "customer_id" -- field name preserved for backward compatibility) |
| `assigned_to` | query | uuid | no | Filter by assigned user |
| `pipeline_id` | query | uuid | no | Filter by pipeline |
| `stage_id` | query | uuid | no | Filter by pipeline stage. Can be combined with pipeline_id or used alone. |
| `created_after` | query | string | no | ISO date filter |
| `created_before` | query | string | no | ISO date filter |
| `limit` | query | number | no | Max results (1-100, default 25) |
| `cursor` | query | string | no | Cursor for next page |
| `expand` | query | string | no | Expansions: contact, referrer, customer, products, assigned_users. "referrer" inlines the referrer contact for opportunities with primary_referrer_contact_id set. |

## Request example

```bash
curl -X GET \
  "https://api.trustpager.com/functions/v1/api/v1/opportunities?status=open&pipeline_id=UUID&stage_id=UUID&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response example

```json
{
  "data": [
    {
      "id": "opp-uuid-...",
      "public_id": "OPP-001",
      "name": "Website Redesign",
      "status": "open",
      "contact_id": "contact-uuid-...",
      "customer_id": "company-uuid-...",
      "currency": "AUD",
      "tags": ["web", "design"],
      "placements": [
        {
          "pipeline_id": "pipe-uuid-...",
          "stage_id": "stage-uuid-...",
          "crm_pipelines": { "id": "pipe-uuid-...", "name": "Sales" },
          "crm_pipeline_stages": { "id": "stage-uuid-...", "name": "Proposal", "color": "#3B82F6" }
        }
      ],
      "created_at": "2026-03-01T09:00:00Z"
    }
  ],
  "pagination": { "limit": 25, "has_more": false, "next_cursor": null, "prev_cursor": null },
  "meta": { "credits_remaining": 9500 }
}
```

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