0
# Lead Management
1
2
Lead tracking and qualification system for potential customers. Leads represent prospective business opportunities that need to be qualified and potentially converted to accounts and opportunities.
3
4
## Capabilities
5
6
### External Lead Creation
7
8
Create leads from external websites using API key authentication.
9
10
```python { .api }
11
def create_lead_from_site(lead_data: dict, api_key: str) -> dict:
12
"""
13
Create lead from external website or system.
14
15
Args:
16
lead_data (dict): Lead information
17
api_key (str): API key for authentication (passed as query parameter)
18
19
Returns:
20
dict: Created lead details
21
22
Authentication:
23
API Key (query parameter: apikey)
24
25
Example:
26
POST /api/leads/create-from-site/?apikey=your-api-key
27
{
28
"first_name": "John",
29
"last_name": "Prospect",
30
"email": "john@prospect.com",
31
"phone": "+1234567890",
32
"account_name": "Prospect Company",
33
"source": "Website Form",
34
"title": "Interested in Product Demo"
35
}
36
37
Response:
38
{
39
"id": "new-lead-uuid",
40
"first_name": "John",
41
"last_name": "Prospect",
42
...lead details...
43
}
44
"""
45
```
46
47
### Lead Listing and Search
48
49
List leads with comprehensive filtering, excluding converted leads.
50
51
```python { .api }
52
def list_leads(name: str = None, title: str = None, source: str = None,
53
assigned_to: str = None, status: str = None, tags: str = None,
54
city: str = None, email: str = None,
55
limit: int = 10, offset: int = 0) -> dict:
56
"""
57
List leads with filtering (excludes converted leads).
58
59
Args:
60
name (str, optional): Filter by first or last name
61
title (str, optional): Filter by lead title
62
source (str, optional): Filter by lead source
63
assigned_to (str, optional): Filter by assigned user UUID
64
status (str, optional): Filter by status ('assigned', 'in process', 'recycled', 'closed')
65
tags (str, optional): Filter by tags
66
city (str, optional): Filter by city
67
email (str, optional): Filter by email
68
limit (int): Results per page (default: 10)
69
offset (int): Results to skip (default: 0)
70
71
Returns:
72
dict: Paginated leads with metadata
73
74
Headers Required:
75
Authorization: Bearer <access_token>
76
organization-id: <org_uuid>
77
78
Example:
79
GET /api/leads/?status=assigned&source=website&limit=5
80
81
Response:
82
{
83
"open_leads": [
84
{
85
"id": "lead-uuid",
86
"title": "Product Demo Request",
87
"first_name": "Jane",
88
"last_name": "Prospect",
89
"email": "jane@prospect.com",
90
"phone": "+1987654321",
91
"status": "assigned",
92
"source": "Website Form",
93
"account_name": "Prospect Corp",
94
"opportunity_amount": "50000.00",
95
"created_on": "2023-01-15T10:30:00Z",
96
"assigned_to": ["user1-uuid"],
97
"tags": ["demo", "qualified"]
98
}
99
],
100
"closed_leads": [],
101
"open_leads_count": 15,
102
"closed_leads_count": 3,
103
"contacts": [...],
104
"users": [...],
105
"source_list": ["Website Form", "Cold Call", "Referral", "Trade Show"],
106
"tags": [...],
107
"status": [...available status options...]
108
}
109
"""
110
```
111
112
### Lead Creation and Auto-Conversion
113
114
Create leads with optional automatic conversion to accounts.
115
116
```python { .api }
117
def create_lead(lead_data: dict, auto_convert: bool = False) -> dict:
118
"""
119
Create new lead with optional auto-conversion to account.
120
121
Args:
122
lead_data (dict): Lead information and associations
123
auto_convert (bool): Whether to automatically convert to account
124
125
Returns:
126
dict: Created lead (and account if auto-converted)
127
128
Headers Required:
129
Authorization: Bearer <access_token>
130
organization-id: <org_uuid>
131
Content-Type: multipart/form-data (if including attachments)
132
133
Example:
134
POST /api/leads/
135
{
136
"title": "Enterprise Software Inquiry",
137
"first_name": "Robert",
138
"last_name": "Johnson",
139
"email": "robert@bigcorp.com",
140
"phone": "+1555987654",
141
"status": "assigned",
142
"source": "Cold Call",
143
"account_name": "Big Corp Industries",
144
"website": "https://bigcorp.com",
145
"description": "Interested in enterprise solution for 500+ users",
146
"opportunity_amount": "75000.00",
147
"contacts": ["contact1-uuid"],
148
"assigned_to": ["user1-uuid"],
149
"teams": ["sales-team-uuid"],
150
"tags": ["enterprise", "qualified"],
151
"address_line": "789 Corporate Blvd",
152
"city": "Dallas",
153
"state": "TX",
154
"postcode": "75201",
155
"country": "USA"
156
}
157
158
Response:
159
{
160
"id": "new-lead-uuid",
161
"title": "Enterprise Software Inquiry",
162
...lead details...,
163
"converted_account": null # or account details if auto-converted
164
}
165
"""
166
```
167
168
### Lead Details and Operations
169
170
Get comprehensive lead information and perform updates.
171
172
```python { .api }
173
def get_lead(pk: str) -> dict:
174
"""
175
Get detailed lead information.
176
177
Args:
178
pk (str): Lead UUID
179
180
Returns:
181
dict: Complete lead details
182
183
Headers Required:
184
Authorization: Bearer <access_token>
185
organization-id: <org_uuid>
186
187
Example:
188
GET /api/leads/lead-uuid/
189
190
Response:
191
{
192
"lead_obj": {
193
"id": "lead-uuid",
194
"title": "Product Demo Request",
195
"first_name": "Jane",
196
"last_name": "Prospect",
197
"email": "jane@prospect.com",
198
"phone": "+1987654321",
199
"status": "in process",
200
"source": "Website Form",
201
"account_name": "Prospect Corp",
202
"website": "https://prospect.com",
203
"description": "Interested in our premium features",
204
"opportunity_amount": "50000.00",
205
"address_line": "456 Business St",
206
"city": "Seattle",
207
"state": "WA",
208
"postcode": "98101",
209
"country": "USA",
210
"created_on": "2023-01-15T10:30:00Z",
211
"created_by": "user-uuid"
212
},
213
"address_obj": {...address details...},
214
"assigned_to": [...assigned users...],
215
"teams": [...assigned teams...],
216
"comments": [...lead comments...],
217
"attachments": [...lead attachments...],
218
"contacts": [...associated contacts...],
219
"users_mention": [...users for @mentions...],
220
"tags": ["demo", "qualified"]
221
}
222
"""
223
224
def update_lead(pk: str, lead_data: dict) -> dict:
225
"""
226
Update lead information.
227
228
Args:
229
pk (str): Lead UUID
230
lead_data (dict): Updated lead information
231
232
Returns:
233
dict: Updated lead details
234
235
Headers Required:
236
Authorization: Bearer <access_token>
237
organization-id: <org_uuid>
238
239
Example:
240
PUT /api/leads/lead-uuid/
241
{
242
"status": "in process",
243
"opportunity_amount": "60000.00",
244
"description": "Updated after discovery call"
245
}
246
"""
247
248
def delete_lead(pk: str) -> None:
249
"""
250
Delete a lead.
251
252
Args:
253
pk (str): Lead UUID
254
255
Returns:
256
None: 204 No Content on success
257
258
Headers Required:
259
Authorization: Bearer <access_token>
260
organization-id: <org_uuid>
261
262
Example:
263
DELETE /api/leads/lead-uuid/
264
"""
265
```
266
267
### Lead Comments and Attachments
268
269
Manage lead activity and documentation.
270
271
```python { .api }
272
def add_lead_comment_or_attachment(pk: str, comment: str = None,
273
attachment: file = None) -> dict:
274
"""
275
Add comment or attachment to lead.
276
277
Args:
278
pk (str): Lead UUID
279
comment (str, optional): Comment text
280
attachment (file, optional): File to attach
281
282
Returns:
283
dict: Success response
284
285
Headers Required:
286
Authorization: Bearer <access_token>
287
organization-id: <org_uuid>
288
Content-Type: multipart/form-data (for attachments)
289
290
Example:
291
POST /api/leads/lead-uuid/
292
{
293
"comment": "Discovery call scheduled for next Tuesday"
294
}
295
"""
296
297
def edit_lead_comment(pk: str, comment: str) -> dict:
298
"""Edit a lead comment."""
299
300
def delete_lead_comment(pk: str) -> None:
301
"""Delete a lead comment."""
302
303
def delete_lead_attachment(pk: str) -> None:
304
"""Delete a lead attachment."""
305
```
306
307
### Bulk Lead Import
308
309
Import multiple leads from file upload.
310
311
```python { .api }
312
def upload_leads(leads_file: file) -> dict:
313
"""
314
Bulk upload leads from file.
315
316
Args:
317
leads_file (file): CSV or Excel file containing lead data
318
319
Returns:
320
dict: Import results and statistics
321
322
Headers Required:
323
Authorization: Bearer <access_token>
324
organization-id: <org_uuid>
325
Content-Type: multipart/form-data
326
327
Example:
328
POST /api/leads/upload/
329
Form Data:
330
leads_file: <file_object>
331
332
Response:
333
{
334
"status": "success",
335
"imported_count": 25,
336
"failed_count": 2,
337
"errors": [...validation errors for failed rows...]
338
}
339
"""
340
```
341
342
### Company Management
343
344
Manage companies associated with leads.
345
346
```python { .api }
347
def list_companies() -> dict:
348
"""
349
List companies from leads.
350
351
Returns:
352
dict: Companies list
353
354
Headers Required:
355
Authorization: Bearer <access_token>
356
organization-id: <org_uuid>
357
358
Example:
359
GET /api/leads/companies/
360
361
Response:
362
{
363
"companies": [
364
{
365
"id": "company-uuid",
366
"name": "Tech Corp",
367
"industry": "Technology",
368
"website": "https://techcorp.com"
369
}
370
]
371
}
372
"""
373
374
def create_company(company_data: dict) -> dict:
375
"""
376
Create new company.
377
378
Args:
379
company_data (dict): Company information
380
381
Returns:
382
dict: Created company details
383
384
Headers Required:
385
Authorization: Bearer <access_token>
386
organization-id: <org_uuid>
387
388
Example:
389
POST /api/leads/companies/
390
{
391
"name": "New Tech Startup",
392
"industry": "Software",
393
"website": "https://newtechstartup.com"
394
}
395
"""
396
397
def get_company(pk: str) -> dict:
398
"""
399
Get company details.
400
401
Args:
402
pk (str): Company UUID
403
404
Returns:
405
dict: Company information
406
407
Headers Required:
408
Authorization: Bearer <access_token>
409
410
Example:
411
GET /api/leads/company/company-uuid/
412
"""
413
```
414
415
## Lead Data Types
416
417
```python { .api }
418
class Lead:
419
"""Lead model for potential customers"""
420
id: str # UUID
421
title: str # Lead title/subject
422
first_name: str # Required
423
last_name: str # Required
424
email: str # Contact email
425
phone: str # Contact phone
426
status: str # Lead status
427
source: str # How lead was acquired
428
account_name: str # Prospective company name
429
website: str # Company website
430
description: str # Lead details
431
opportunity_amount: decimal # Potential deal value
432
433
# Address information
434
address_line: str
435
street: str
436
city: str
437
state: str
438
postcode: str
439
country: str
440
441
# Metadata
442
created_on: datetime
443
created_by: str # User UUID
444
org: str # Organization UUID
445
446
# Associations
447
contacts: list[str] # Contact UUIDs
448
assigned_to: list[str] # User UUIDs
449
teams: list[str] # Team UUIDs
450
tags: list[str] # Tag names
451
452
class LeadStatus:
453
"""Lead status options"""
454
ASSIGNED: str = "assigned"
455
IN_PROCESS: str = "in process"
456
CONVERTED: str = "converted" # Converted to account (filtered from lists)
457
RECYCLED: str = "recycled"
458
CLOSED: str = "closed"
459
460
class LeadSource:
461
"""Common lead sources"""
462
WEBSITE: str = "Website Form"
463
COLD_CALL: str = "Cold Call"
464
REFERRAL: str = "Referral"
465
TRADE_SHOW: str = "Trade Show"
466
EMAIL_CAMPAIGN: str = "Email Campaign"
467
SOCIAL_MEDIA: str = "Social Media"
468
ADVERTISEMENT: str = "Advertisement"
469
470
class Company:
471
"""Company information from leads"""
472
id: str # UUID
473
name: str # Company name
474
industry: str # Industry type
475
website: str # Company website
476
created_from_lead: str # Lead UUID that created company
477
```
478
479
## Lead Lifecycle
480
481
1. **Lead Creation**: From external forms, manual entry, or imports
482
2. **Assignment**: Assign to sales team members
483
3. **Qualification**: Update status to "in process" and gather information
484
4. **Conversion**: Convert qualified leads to accounts and opportunities
485
5. **Closure**: Mark unqualified leads as "closed" or "recycled"
486
487
Converted leads are filtered out of standard lead lists but remain in the system for historical tracking.
488
489
## Integration Features
490
491
- **External API**: Allows website forms and other systems to create leads
492
- **Bulk Import**: CSV/Excel import for large lead lists
493
- **Auto-Conversion**: Automatic account creation for qualified leads
494
- **Tag System**: Custom categorization and organization
495
- **Assignment Rules**: Distribute leads to appropriate team members