0
# Opportunity Management
1
2
Sales opportunity tracking with deal stages, probability management, and revenue forecasting. Opportunities represent specific sales deals being pursued with accounts and contacts.
3
4
## Capabilities
5
6
### Opportunity Listing and Search
7
8
List opportunities with filtering by various criteria.
9
10
```python { .api }
11
def list_opportunities(name: str = None, account: str = None, stage: str = None,
12
lead_source: str = None, tags: str = None,
13
limit: int = 10, offset: int = 0) -> dict:
14
"""
15
List opportunities with filtering.
16
17
Args:
18
name (str, optional): Filter by opportunity name
19
account (str, optional): Filter by account name
20
stage (str, optional): Filter by sales stage
21
lead_source (str, optional): Filter by lead source
22
tags (str, optional): Filter by tags
23
limit (int): Results per page (default: 10)
24
offset (int): Results to skip (default: 0)
25
26
Returns:
27
dict: Paginated opportunities with metadata
28
29
Headers Required:
30
Authorization: Bearer <access_token>
31
organization-id: <org_uuid>
32
33
Example:
34
GET /api/opportunities/?stage=QUALIFICATION&limit=5
35
36
Response:
37
{
38
"count": 20,
39
"next": "/api/opportunities/?limit=5&offset=5",
40
"previous": null,
41
"results": [
42
{
43
"id": "opp-uuid",
44
"name": "Enterprise Software Deal",
45
"account": "ACME Corporation",
46
"stage": "QUALIFICATION",
47
"amount": "75000.00",
48
"currency": "USD",
49
"probability": 25,
50
"expected_close_date": "2023-03-15",
51
"lead_source": "Cold Call",
52
"created_on": "2023-01-15T10:30:00Z",
53
"assigned_to": ["user1-uuid"],
54
"tags": ["enterprise", "software"]
55
}
56
],
57
"accounts_list": [...],
58
"contacts_list": [...],
59
"users": [...],
60
"teams": [...]
61
}
62
"""
63
```
64
65
### Opportunity Creation
66
67
Create new sales opportunities with comprehensive details.
68
69
```python { .api }
70
def create_opportunity(opportunity_data: dict) -> dict:
71
"""
72
Create new opportunity.
73
74
Args:
75
opportunity_data (dict): Opportunity information and associations
76
77
Returns:
78
dict: Created opportunity details
79
80
Headers Required:
81
Authorization: Bearer <access_token>
82
organization-id: <org_uuid>
83
Content-Type: multipart/form-data (if including attachments)
84
85
Example:
86
POST /api/opportunities/
87
{
88
"name": "Q1 Software License Deal",
89
"account": "account-uuid",
90
"stage": "NEEDS ANALYSIS",
91
"amount": "125000.00",
92
"currency": "USD",
93
"probability": 40,
94
"expected_close_date": "2023-04-30",
95
"lead_source": "Referral",
96
"description": "Annual software licensing opportunity",
97
"contacts": ["contact1-uuid", "contact2-uuid"],
98
"assigned_to": ["user1-uuid"],
99
"teams": ["sales-team-uuid"],
100
"tags": ["software", "annual-contract"]
101
}
102
103
Response:
104
{
105
"id": "new-opp-uuid",
106
"name": "Q1 Software License Deal",
107
...opportunity details...
108
}
109
"""
110
```
111
112
### Opportunity Details and Operations
113
114
Get comprehensive opportunity information and perform updates.
115
116
```python { .api }
117
def get_opportunity(pk: str) -> dict:
118
"""
119
Get detailed opportunity information.
120
121
Args:
122
pk (str): Opportunity UUID
123
124
Returns:
125
dict: Complete opportunity details
126
127
Headers Required:
128
Authorization: Bearer <access_token>
129
organization-id: <org_uuid>
130
131
Example:
132
GET /api/opportunities/opp-uuid/
133
134
Response:
135
{
136
"opportunity_obj": {
137
"id": "opp-uuid",
138
"name": "Enterprise Software Deal",
139
"account": "account-uuid",
140
"stage": "VALUE PROPOSITION",
141
"amount": "75000.00",
142
"currency": "USD",
143
"probability": 60,
144
"expected_close_date": "2023-03-15",
145
"actual_close_date": null,
146
"lead_source": "Cold Call",
147
"description": "Enterprise software solution for 200+ users",
148
"created_on": "2023-01-15T10:30:00Z",
149
"created_by": "user-uuid"
150
},
151
"account_obj": {...account details...},
152
"contacts": [...associated contacts...],
153
"assigned_to": [...assigned users...],
154
"teams": [...assigned teams...],
155
"comments": [...opportunity comments...],
156
"attachments": [...opportunity attachments...],
157
"users_mention": [...users for @mentions...],
158
"tags": ["enterprise", "software"]
159
}
160
"""
161
162
def update_opportunity(pk: str, opportunity_data: dict) -> dict:
163
"""
164
Update opportunity information.
165
166
Args:
167
pk (str): Opportunity UUID
168
opportunity_data (dict): Updated opportunity information
169
170
Returns:
171
dict: Updated opportunity details
172
173
Headers Required:
174
Authorization: Bearer <access_token>
175
organization-id: <org_uuid>
176
177
Example:
178
PUT /api/opportunities/opp-uuid/
179
{
180
"stage": "PROPOSAL/QUOTATION",
181
"probability": 75,
182
"amount": "80000.00"
183
}
184
"""
185
186
def delete_opportunity(pk: str) -> None:
187
"""
188
Delete an opportunity.
189
190
Args:
191
pk (str): Opportunity UUID
192
193
Returns:
194
None: 204 No Content on success
195
196
Headers Required:
197
Authorization: Bearer <access_token>
198
organization-id: <org_uuid>
199
200
Example:
201
DELETE /api/opportunities/opp-uuid/
202
"""
203
```
204
205
### Opportunity Comments and Attachments
206
207
Manage opportunity activity and supporting documents.
208
209
```python { .api }
210
def add_opportunity_comment_or_attachment(pk: str, comment: str = None,
211
attachment: file = None) -> dict:
212
"""
213
Add comment or attachment to opportunity.
214
215
Args:
216
pk (str): Opportunity UUID
217
comment (str, optional): Comment text
218
attachment (file, optional): File to attach
219
220
Returns:
221
dict: Success response
222
223
Headers Required:
224
Authorization: Bearer <access_token>
225
organization-id: <org_uuid>
226
Content-Type: multipart/form-data (for attachments)
227
228
Example:
229
POST /api/opportunities/opp-uuid/
230
{
231
"comment": "Proposal submitted, awaiting client review"
232
}
233
"""
234
235
def edit_opportunity_comment(pk: str, comment: str) -> dict:
236
"""Edit an opportunity comment."""
237
238
def delete_opportunity_comment(pk: str) -> None:
239
"""Delete an opportunity comment."""
240
241
def delete_opportunity_attachment(pk: str) -> None:
242
"""Delete an opportunity attachment."""
243
```
244
245
## Opportunity Data Types
246
247
```python { .api }
248
class Opportunity:
249
"""Opportunity model for sales deals"""
250
id: str # UUID
251
name: str # Opportunity name (required)
252
account: str # Account UUID (required)
253
stage: str # Sales stage
254
amount: decimal # Deal value
255
currency: str # Currency code (default: USD)
256
probability: int # Win probability (0-100%)
257
expected_close_date: date # Projected close date
258
actual_close_date: date # Actual close date (when closed)
259
lead_source: str # Original lead source
260
description: str # Opportunity details
261
262
# Metadata
263
created_on: datetime
264
created_by: str # User UUID
265
org: str # Organization UUID
266
267
# Associations
268
contacts: list[str] # Contact UUIDs
269
assigned_to: list[str] # User UUIDs
270
teams: list[str] # Team UUIDs
271
tags: list[str] # Tag names
272
273
class OpportunityStage:
274
"""Sales stages for opportunity pipeline"""
275
QUALIFICATION: str = "QUALIFICATION"
276
NEEDS_ANALYSIS: str = "NEEDS ANALYSIS"
277
VALUE_PROPOSITION: str = "VALUE PROPOSITION"
278
PROPOSAL_QUOTATION: str = "PROPOSAL/QUOTATION"
279
NEGOTIATION_REVIEW: str = "NEGOTIATION/REVIEW"
280
CLOSED_WON: str = "CLOSED WON"
281
CLOSED_LOST: str = "CLOSED LOST"
282
283
class Currency:
284
"""Supported currencies"""
285
USD: str = "USD"
286
EUR: str = "EUR"
287
GBP: str = "GBP"
288
# Additional currencies as configured
289
290
class OpportunityComment:
291
"""Comments on opportunities"""
292
id: str # UUID
293
comment: str
294
opportunity: str # Opportunity UUID
295
commented_on: datetime
296
commented_by: str # User UUID
297
298
class OpportunityAttachment:
299
"""File attachments on opportunities"""
300
id: str # UUID
301
attachment: str # File path/URL
302
opportunity: str # Opportunity UUID
303
created_on: datetime
304
created_by: str # User UUID
305
```
306
307
## Sales Pipeline Management
308
309
Opportunities follow a structured sales process:
310
311
1. **QUALIFICATION**: Initial assessment of fit and budget
312
2. **NEEDS ANALYSIS**: Understanding customer requirements
313
3. **VALUE PROPOSITION**: Presenting solution benefits
314
4. **PROPOSAL/QUOTATION**: Formal proposal and pricing
315
5. **NEGOTIATION/REVIEW**: Contract terms and final details
316
6. **CLOSED WON**: Successfully won the deal
317
7. **CLOSED LOST**: Lost the opportunity
318
319
Each stage typically corresponds to increasing probability percentages and advancing close dates.
320
321
## Revenue Forecasting
322
323
Opportunities support revenue forecasting through:
324
- **Amount**: Deal value in specified currency
325
- **Probability**: Win likelihood (0-100%)
326
- **Expected Close Date**: Projected closing timeline
327
- **Stage**: Current position in sales pipeline
328
329
Weighted forecasting can be calculated as: Amount × Probability = Weighted Value
330
331
## Integration Points
332
333
- **Accounts**: Every opportunity must be linked to an account
334
- **Contacts**: Key stakeholders and decision makers
335
- **Leads**: Opportunities often originate from converted leads
336
- **Tasks**: Action items and follow-up activities
337
- **Events**: Meetings and calls related to the deal
338
- **Documents**: Proposals, contracts, and supporting materials