0
# Document Management
1
2
File upload, storage, and sharing system with document organization, team-based sharing permissions, and attachment capabilities across all CRM entities.
3
4
## Capabilities
5
6
### Document Listing and Search
7
8
List and search documents with filtering options.
9
10
```python { .api }
11
def list_documents(title: str = None, status: str = None, shared_with: str = None,
12
limit: int = 10, offset: int = 0) -> dict:
13
"""
14
List documents with filtering and search.
15
16
Args:
17
title (str, optional): Filter by document title (partial match)
18
status (str, optional): Filter by status ('active', 'inactive')
19
shared_with (str, optional): Filter by shared team UUID
20
limit (int): Number of results per page (default: 10)
21
offset (int): Number of results to skip (default: 0)
22
23
Returns:
24
dict: Paginated documents with metadata
25
26
Headers Required:
27
Authorization: Bearer <access_token>
28
organization-id: <org_uuid>
29
30
Example:
31
GET /api/documents/?status=active&limit=5
32
33
Response:
34
{
35
"count": 18,
36
"next": "/api/documents/?limit=5&offset=5",
37
"previous": null,
38
"results": [
39
{
40
"id": "document-uuid",
41
"title": "Product Specification v2.1",
42
"document_file": "/media/documents/product_spec_v21.pdf",
43
"status": "active",
44
"shared_with": ["team1-uuid", "team2-uuid"],
45
"created_on": "2023-01-15T10:30:00Z",
46
"created_by": {
47
"id": "user-uuid",
48
"first_name": "John",
49
"last_name": "Smith",
50
"email": "john.smith@company.com"
51
}
52
}
53
]
54
}
55
"""
56
```
57
58
### Document Upload and Creation
59
60
Upload and create new documents with sharing permissions.
61
62
```python { .api }
63
def create_document(document_data: dict, document_file: file) -> dict:
64
"""
65
Upload and create a new document.
66
67
Args:
68
document_data (dict): Document metadata and sharing information
69
document_file (file): File to upload
70
71
Returns:
72
dict: Created document details
73
74
Headers Required:
75
Authorization: Bearer <access_token>
76
organization-id: <org_uuid>
77
Content-Type: multipart/form-data
78
79
Example:
80
POST /api/documents/
81
Content-Type: multipart/form-data
82
83
Form data:
84
{
85
"title": "Contract Template 2023",
86
"status": "active",
87
"shared_with": ["sales-team-uuid", "legal-team-uuid"],
88
"document_file": <file upload>
89
}
90
91
Response:
92
{
93
"id": "new-document-uuid",
94
"title": "Contract Template 2023",
95
"document_file": "/media/documents/contract_template_2023.docx",
96
"status": "active",
97
"shared_with": ["sales-team-uuid", "legal-team-uuid"],
98
"created_on": "2023-02-01T09:00:00Z",
99
"created_by": {
100
"id": "user-uuid",
101
"first_name": "Alice",
102
"last_name": "Johnson",
103
"email": "alice.johnson@company.com"
104
}
105
}
106
"""
107
```
108
109
### Document Details and Operations
110
111
Get comprehensive document information and perform updates.
112
113
```python { .api }
114
def get_document(pk: str) -> dict:
115
"""
116
Get detailed document information.
117
118
Args:
119
pk (str): Document UUID
120
121
Returns:
122
dict: Complete document details with sharing information
123
124
Headers Required:
125
Authorization: Bearer <access_token>
126
organization-id: <org_uuid>
127
128
Example:
129
GET /api/documents/document-uuid/
130
131
Response:
132
{
133
"document_obj": {
134
"id": "document-uuid",
135
"title": "Product Specification v2.1",
136
"document_file": "/media/documents/product_spec_v21.pdf",
137
"status": "active",
138
"created_on": "2023-01-15T10:30:00Z",
139
"created_by": "user-uuid"
140
},
141
"shared_with": [
142
{
143
"id": "team1-uuid",
144
"name": "Product Team",
145
"users": [...team members...]
146
},
147
{
148
"id": "team2-uuid",
149
"name": "Sales Team",
150
"users": [...team members...]
151
}
152
],
153
"created_by": {
154
"id": "user-uuid",
155
"first_name": "John",
156
"last_name": "Smith",
157
"email": "john.smith@company.com"
158
}
159
}
160
"""
161
162
def update_document(pk: str, document_data: dict) -> dict:
163
"""
164
Update document information and sharing permissions.
165
166
Args:
167
pk (str): Document UUID
168
document_data (dict): Updated document information
169
170
Returns:
171
dict: Updated document details
172
173
Headers Required:
174
Authorization: Bearer <access_token>
175
organization-id: <org_uuid>
176
177
Example:
178
PUT /api/documents/document-uuid/
179
{
180
"title": "Product Specification v2.2 - FINAL",
181
"status": "active",
182
"shared_with": ["product-team-uuid", "sales-team-uuid", "support-team-uuid"]
183
}
184
"""
185
186
def delete_document(pk: str) -> None:
187
"""
188
Delete a document.
189
190
Args:
191
pk (str): Document 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/documents/document-uuid/
202
"""
203
```
204
205
## Document Data Types
206
207
```python { .api }
208
class Document:
209
"""Document model for file storage and sharing"""
210
id: str # UUID
211
title: str # Required document title
212
document_file: str # File path/URL to uploaded document
213
status: str # 'active' or 'inactive'
214
215
# Sharing and permissions
216
shared_with: list[str] # Team UUIDs that have access
217
218
# Metadata
219
created_on: datetime
220
created_by: str # User UUID
221
org: str # Organization UUID
222
223
class DocumentSharing:
224
"""Document sharing information with teams"""
225
team_id: str # Team UUID
226
team_name: str # Team name
227
users: list[User] # Team members with access
228
229
class DocumentCreator:
230
"""Document creator information"""
231
id: str # User UUID
232
first_name: str
233
last_name: str
234
email: str
235
```
236
237
## Document Management Features
238
239
### File Upload Support
240
Documents support various file types including:
241
242
- **Office Documents**: .docx, .xlsx, .pptx, .pdf
243
- **Images**: .jpg, .png, .gif, .svg
244
- **Text Files**: .txt, .csv, .json, .xml
245
- **Archives**: .zip, .tar, .gz
246
- **Other formats**: Based on organization settings and security policies
247
248
### Document Status Management
249
Documents can be in different states:
250
251
- **Active**: Document is available and accessible to shared teams
252
- **Inactive**: Document is archived or temporarily unavailable
253
254
### Team-Based Sharing
255
Documents use team-based permissions:
256
257
- **Shared Teams**: Only members of shared teams can access the document
258
- **Creator Access**: Document creator always has access
259
- **Organization Scoping**: Documents are always scoped to the organization
260
261
### Version Control
262
While not explicitly versioned, documents support:
263
264
- **Update Capability**: Replace document content while maintaining sharing
265
- **Metadata Tracking**: Creation date and creator information
266
- **Title Updates**: Modify titles to indicate versions (e.g., "v2.1", "FINAL")
267
268
## Search and Filtering
269
270
Documents support multiple search and filter options:
271
272
- **Title Search**: `title` parameter for partial text matching
273
- **Status Filter**: Filter by active or inactive documents
274
- **Team Sharing**: `shared_with` filter for team-based access
275
- **Creator Filter**: Filter documents by creator (implicit)
276
- **Date Range**: Filter by creation date (implicit)
277
278
All text-based filters support partial matching and are case-insensitive.
279
280
## Document Integration
281
282
Documents can be used across CRM entities as attachments:
283
284
- **Account Attachments**: Link documents to customer accounts
285
- **Contact Attachments**: Associate documents with individual contacts
286
- **Lead Attachments**: Attach documents to sales leads
287
- **Opportunity Attachments**: Include proposals, contracts in opportunities
288
- **Task Attachments**: Add supporting files to tasks
289
- **Event Attachments**: Meeting materials and agendas
290
- **Case Attachments**: Support documentation and screenshots
291
292
## Security and Access Control
293
294
### Organization Isolation
295
- All documents are scoped to the user's organization
296
- Cross-organization access is not permitted
297
298
### Team-Based Permissions
299
- Only users in shared teams can access documents
300
- Document creators always retain access
301
- Team membership changes affect document access
302
303
### File Security
304
- Uploaded files are stored securely with unique identifiers
305
- File access is controlled through API authentication
306
- Direct file URLs may require additional authorization
307
308
## Best Practices
309
310
### Document Organization
311
- Use descriptive titles with version information
312
- Organize documents by sharing them with relevant teams
313
- Keep document status updated (active/inactive)
314
315
### Sharing Management
316
- Share documents with the minimum required teams
317
- Review sharing permissions regularly
318
- Use team structure to manage document access efficiently
319
320
### File Management
321
- Use appropriate file formats for the intended use
322
- Keep file sizes reasonable for performance
323
- Include version information in filenames when appropriate