0
# Django CRM
1

2
Django CRM is an open-source Customer Relationship Management system built on the Django web framework with Django REST Framework. It provides a comprehensive CRM solution with contact management, lead tracking, account management, opportunity management, task management, event management, case management, and team collaboration, all accessible through a REST API with JWT authentication.
3

4
## Package Information
5

6
- **Package Name**: django-crm
7
- **Package Type**: Python Django Application
8
- **Language**: Python (Django/DRF)
9
- **Version**: 0.10.0
10
- **Installation**: Clone and deploy Django application or integrate as Django package
11
- **Authentication**: JWT (JSON Web Tokens)
12
- **API Base URL**: `/api/`
13

14
## Core Setup
15

16
### Django Integration
17

18
```python
19
# settings.py
20
INSTALLED_APPS = [
21
    'rest_framework',
22
    'rest_framework_simplejwt',
23
    'corsheaders',
24
    'drf_spectacular',
25
    'common',
26
    'accounts',
27
    'cases',
28
    'contacts',
29
    'emails',
30
    'leads',
31
    'opportunity',
32
    'planner',
33
    'tasks',
34
    'invoices',
35
    'events',
36
    'teams',
37
]
38

39
# API Configuration
40
REST_FRAMEWORK = {
41
    'DEFAULT_AUTHENTICATION_CLASSES': (
42
        'rest_framework_simplejwt.authentication.JWTAuthentication',
43
    ),
44
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
45
    'PAGE_SIZE': 10,
46
}
47
```
48

49
### URL Configuration
50

51
```python
52
# urls.py
53
from django.urls import path, include
54

55
urlpatterns = [
56
    path('api/', include('common.app_urls', namespace='common_urls')),
57
    path('schema/', SpectacularAPIView.as_view(), name='schema'),
58
    path('swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
59
]
60
```
61

62
## Basic Usage
63

64
### Authentication
65

66
```python
67
import requests
68

69
# Login (if implementing custom auth)
70
response = requests.post('http://your-crm.com/api/auth/google/', {
71
    'token': 'google_oauth_token'
72
})
73
token_data = response.json()
74
access_token = token_data['access']
75

76
# Set up headers for authenticated requests
77
headers = {
78
    'Authorization': f'Bearer {access_token}',
79
    'organization-id': 'your_org_uuid',  # Required for org-scoped operations
80
    'Content-Type': 'application/json'
81
}
82
```
83

84
### Basic API Operations
85

86
```python
87
import requests
88

89
# Get dashboard data
90
dashboard = requests.get('http://your-crm.com/api/dashboard/', headers=headers)
91
print(dashboard.json())
92

93
# Create a contact
94
contact_data = {
95
    'first_name': 'John',
96
    'last_name': 'Doe',
97
    'primary_email': 'john.doe@example.com',
98
    'mobile_number': '+1234567890',
99
    'assigned_to': ['user_uuid']
100
}
101
response = requests.post('http://your-crm.com/api/contacts/',
102
                        json=contact_data, headers=headers)
103
contact = response.json()
104

105
# Create a lead
106
lead_data = {
107
    'first_name': 'Jane',
108
    'last_name': 'Smith',
109
    'email': 'jane.smith@company.com',
110
    'phone': '+1987654321',
111
    'status': 'assigned',
112
    'source': 'Website',
113
    'account_name': 'ACME Corp',
114
    'contacts': [contact['id']],
115
    'assigned_to': ['user_uuid']
116
}
117
response = requests.post('http://your-crm.com/api/leads/',
118
                        json=lead_data, headers=headers)
119
lead = response.json()
120
```
121

122
## Architecture
123

124
Django CRM follows a modular Django application architecture with these key components:
125

126
- **Organization-based Multi-tenancy**: All data is scoped by organization with role-based access control
127
- **Django REST Framework API**: Complete REST API for all CRM operations
128
- **JWT Authentication**: Token-based authentication with refresh token support
129
- **Celery Background Tasks**: Asynchronous processing for emails and bulk operations
130
- **File Attachment Support**: Upload and manage files attached to CRM entities
131
- **Comprehensive Activity Tracking**: Comments and audit trails for all entities
132

133
The system is designed around these main entity types:
134
- **Accounts**: Customer companies/organizations
135
- **Contacts**: Individual people within accounts
136
- **Leads**: Potential customers being qualified
137
- **Opportunities**: Sales deals being pursued
138
- **Tasks**: Work items and to-dos
139
- **Events**: Calendar events and meetings
140
- **Cases**: Support cases and issues
141
- **Teams**: User groups for collaboration
142

143
## Capabilities
144

145
### Authentication & User Management
146

147
Core authentication, user management, organization management, and administrative functions including JWT token handling, Google OAuth integration, user roles, and organization-scoped operations.
148

149
```python { .api }
150
# Authentication endpoints
151
POST /api/auth/google/  # Google OAuth login
152
POST /api/auth/refresh-token/  # Refresh JWT token
153

154
# User management
155
GET /api/profile/  # Get current user profile
156
GET /api/users/  # List organization users
157
POST /api/users/  # Create new user
158
GET /api/user/<str:pk>/  # Get user details
159
PUT /api/user/<str:pk>/  # Update user
160
DELETE /api/user/<str:pk>/  # Delete user
161
POST /api/user/<str:pk>/status/  # Update user status
162
GET /api/users/get-teams-and-users/  # Get teams and users list
163

164
# Organization management
165
GET /api/org/  # Get user organizations
166
POST /api/org/  # Create organization
167

168
# API settings and domains
169
GET /api/api-settings/  # List API domain settings
170
POST /api/api-settings/  # Create API domain setting
171
GET /api/api-settings/<str:pk>/  # Get domain setting details
172
PUT /api/api-settings/<str:pk>/  # Update domain setting
173
DELETE /api/api-settings/<str:pk>/  # Delete domain setting
174
```
175

176
[Authentication & Users](./authentication.md)
177

178
### Account Management
179

180
Customer account management including company information, billing details, contact associations, team assignments, and account-related activities. Supports both open and closed account states with comprehensive search and filtering.
181

182
```python { .api }
183
GET /api/accounts/  # List accounts with filtering
184
POST /api/accounts/  # Create new account
185
GET /api/accounts/<str:pk>/  # Get account details
186
PUT /api/accounts/<str:pk>/  # Update account
187
DELETE /api/accounts/<str:pk>/  # Delete account
188
POST /api/accounts/<str:pk>/create_mail/  # Send email from account
189
POST /api/accounts/comment/<str:pk>/  # Add comment to account
190
POST /api/accounts/attachment/<str:pk>/  # Add attachment to account
191
```
192

193
[Account Management](./accounts.md)
194

195
### Contact Management
196

197
Individual contact management with personal information, organizational relationships, address details, and contact history. Contacts can be associated with accounts and assigned to team members.
198

199
```python { .api }
200
GET /api/contacts/  # List contacts with search/filtering
201
POST /api/contacts/  # Create new contact
202
GET /api/contacts/<str:pk>/  # Get contact details
203
PUT /api/contacts/<str:pk>/  # Update contact
204
DELETE /api/contacts/<str:pk>/  # Delete contact
205
POST /api/contacts/comment/<str:pk>/  # Add comment to contact
206
POST /api/contacts/attachment/<str:pk>/  # Add attachment to contact
207
```
208

209
[Contact Management](./contacts.md)
210

211
### Lead Management
212

213
Lead tracking and qualification system with lead sources, status management, conversion to accounts, bulk import capabilities, and external API integration for lead capture.
214

215
```python { .api }
216
POST /api/leads/create-from-site/  # External lead creation (API key auth)
217
GET /api/leads/  # List leads (excludes converted)
218
POST /api/leads/  # Create lead (with auto-conversion option)
219
POST /api/leads/upload/  # Bulk lead import
220
GET /api/leads/<str:pk>/  # Get lead details
221
PUT /api/leads/<str:pk>/  # Update lead
222
DELETE /api/leads/<str:pk>/  # Delete lead
223
POST /api/leads/comment/<str:pk>/  # Add comment to lead
224
POST /api/leads/attachment/<str:pk>/  # Add attachment to lead
225
GET /api/leads/companies/  # List lead companies
226
GET /api/leads/company/<str:pk>/  # Get company details
227
```
228

229
[Lead Management](./leads.md)
230

231
### Opportunity Management
232

233
Sales opportunity tracking with deal stages, probability management, revenue forecasting, contact associations, and pipeline management from lead qualification through close.
234

235
```python { .api }
236
GET /api/opportunities/  # List opportunities with filtering
237
POST /api/opportunities/  # Create new opportunity
238
GET /api/opportunities/<str:pk>/  # Get opportunity details
239
PUT /api/opportunities/<str:pk>/  # Update opportunity
240
DELETE /api/opportunities/<str:pk>/  # Delete opportunity
241
POST /api/opportunities/comment/<str:pk>/  # Add comment to opportunity
242
POST /api/opportunities/attachment/<str:pk>/  # Add attachment to opportunity
243
```
244

245
[Opportunity Management](./opportunities.md)
246

247
### Task Management
248

249
Task and to-do management with priority levels, due dates, assignments, status tracking, and integration with accounts, contacts, and other CRM entities.
250

251
```python { .api }
252
GET /api/tasks/  # List tasks
253
POST /api/tasks/  # Create new task
254
GET /api/tasks/<str:pk>/  # Get task details
255
PUT /api/tasks/<str:pk>/  # Update task
256
DELETE /api/tasks/<str:pk>/  # Delete task
257
POST /api/tasks/comment/<str:pk>/  # Add comment to task
258
POST /api/tasks/attachment/<str:pk>/  # Add attachment to task
259
```
260

261
[Task Management](./tasks.md)
262

263
### Event Management
264

265
Calendar event management with scheduling, contact invitations, event types (calls, meetings, tasks), and integration with CRM entities for comprehensive activity tracking.
266

267
```python { .api }
268
GET /api/events/  # List events
269
POST /api/events/  # Create new event
270
GET /api/events/<str:pk>/  # Get event details
271
PUT /api/events/<str:pk>/  # Update event
272
DELETE /api/events/<str:pk>/  # Delete event
273
POST /api/events/comment/<str:pk>/  # Add comment to event
274
POST /api/events/attachment/<str:pk>/  # Add attachment to event
275
```
276

277
[Event Management](./events.md)
278

279
### Case Management
280

281
Support case tracking with priority levels, case types, status management, resolution tracking, and integration with accounts and contacts for comprehensive customer support.
282

283
```python { .api }
284
GET /api/cases/  # List cases
285
POST /api/cases/  # Create new case
286
GET /api/cases/<str:pk>/  # Get case details
287
PUT /api/cases/<str:pk>/  # Update case
288
DELETE /api/cases/<str:pk>/  # Delete case
289
POST /api/cases/comment/<str:pk>/  # Add comment to case
290
POST /api/cases/attachment/<str:pk>/  # Add attachment to case
291
```
292

293
[Case Management](./cases.md)
294

295
### Invoice Management
296

297
Invoice creation, management, and billing operations including invoice generation, status tracking, payment management, and PDF generation. Complete invoice lifecycle from creation through payment with email notifications.
298

299
**Note**: Invoice API endpoints are implemented but not currently routed in the main application URLs. Add to URL routing to enable.
300

301
```python { .api }
302
GET /api/invoices/  # List invoices with filtering
303
POST /api/invoices/  # Create new invoice
304
GET /api/invoices/<str:pk>/  # Get invoice details
305
PUT /api/invoices/<str:pk>/  # Update invoice
306
DELETE /api/invoices/<str:pk>/  # Delete invoice
307
POST /api/invoices/<str:pk>/send-mail/  # Send invoice by email
308
POST /api/invoices/<str:pk>/download/  # Download invoice PDF
309
POST /api/invoices/<str:pk>/status/  # Update invoice status
310
POST /api/invoices/comment/<str:pk>/  # Add comment to invoice
311
POST /api/invoices/attachment/<str:pk>/  # Add attachment to invoice
312
```
313

314
[Invoice Management](./invoices.md)
315

316
### Team Management
317

318
Team creation and management for organizing users into collaborative groups, enabling team-based assignments and permissions across all CRM entities.
319

320
```python { .api }
321
GET /api/teams/  # List organization teams
322
POST /api/teams/  # Create new team
323
GET /api/teams/<str:pk>/  # Get team details
324
PUT /api/teams/<str:pk>/  # Update team
325
DELETE /api/teams/<str:pk>/  # Delete team
326
```
327

328
[Team Management](./teams.md)
329

330
### Document Management
331

332
File upload, storage, and sharing system with document organization, team-based sharing permissions, and attachment capabilities across all CRM entities.
333

334
```python { .api }
335
GET /api/documents/  # List documents (active/inactive)
336
POST /api/documents/  # Upload new document
337
GET /api/documents/<str:pk>/  # Get document details
338
PUT /api/documents/<str:pk>/  # Update document
339
DELETE /api/documents/<str:pk>/  # Delete document
340
```
341

342
[Document Management](./documents.md)
343

344
## Common Data Types
345

346
```python { .api }
347
class User:
348
    """Django CRM User model with organization-based multi-tenancy"""
349
    id: str  # UUID
350
    email: str
351
    first_name: str
352
    last_name: str
353
    role: str  # 'ADMIN' or 'USER'
354
    phone: str
355
    is_active: bool
356
    org: str  # Organization UUID
357
    address: dict  # Address fields
358

359
class Organization:
360
    """Organization/Company for multi-tenant scoping"""
361
    id: str  # UUID
362
    name: str
363
    slug: str
364
    billing_address: dict
365
    billing_city: str
366
    billing_state: str
367

368
class Address:
369
    """Common address structure used across entities"""
370
    address_line: str
371
    street: str
372
    city: str
373
    state: str
374
    postcode: str
375
    country: str
376

377
class Comment:
378
    """Comments available on all major entities"""
379
    id: str  # UUID
380
    comment: str
381
    commented_on: datetime
382
    commented_by: User
383

384
class Attachment:
385
    """File attachments for entities"""
386
    id: str  # UUID
387
    attachment: str  # File path/URL
388
    created_on: datetime
389
    created_by: User
390
```
391

392
## Error Responses
393

394
```python { .api }
395
class ErrorResponse:
396
    """Standard error response format"""
397
    detail: str  # Error message
398
    field_errors: dict  # Field-specific validation errors
399

400
class ValidationErrorResponse:
401
    """Validation error response"""
402
    field_name: list[str]  # List of error messages for the field
403
```
404

405
## Pagination
406

407
```python { .api }
408
class PaginatedResponse:
409
    """Standard pagination format for list endpoints"""
410
    count: int  # Total number of items
411
    next: str | None  # URL for next page
412
    previous: str | None  # URL for previous page
413
    results: list  # Array of items for current page
414
```
415

416
All list endpoints return paginated results using Django REST Framework's `LimitOffsetPagination` with a default page size of 10 items. Use `?limit=N&offset=M` parameters to control pagination.