# POST /opportunities

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

Create a new opportunity. name is required. Set skip_automations: true to suppress the deal_created trigger -- recommended for historical imports to avoid spamming contacts with automation emails. Legacy alias: POST /deals.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `name` | body | string | yes | Opportunity name |
| `contact_id` | body | uuid | no | Primary contact ID |
| `customer_id` | body | uuid | no | Company ID (field name preserved for backward compatibility) |
| `status` | body | string | no | Status (open, won, lost) |
| `currency` | body | string | no | Currency code (default: AUD) |
| `lead_source` | body | string | no | Lead source |
| `tags` | body | object[] | no | Tags. Each tag is {name: string, color?: string} (hex color, default "#3b82f6"). Plain strings are also accepted and auto-converted. Example: [{"name":"hot-lead","color":"#ef4444"}] |
| `notes` | body | string | no | Notes |
| `metadata` | body | object | no | Custom field values as { field_id: value } pairs. Use GET /crm-settings to discover available custom fields. Reserved key: "quick_links" stores per-opportunity Quick Link URLs as { <type-uuid>: <url> } -- define types via PATCH /company/crm-settings. UUID-shaped keys at metadata root are rejected (400). |
| `skip_automations` | body | boolean | no | Set true to suppress the deal_created trigger. Use for historical imports so old opportunities do not trigger automation emails. Default false. |

## Request example

```bash
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/opportunities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Redesign",
    "contact_id": "contact-uuid-...",
    "customer_id": "company-uuid-...",
    "currency": "AUD"
  }'
```

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