0
# Contact Management
1

2
Individual contact management for people within customer organizations. Contacts represent individual persons who can be associated with accounts, included in opportunities, assigned tasks, and participate in various CRM activities.
3

4
## Capabilities
5

6
### Contact Listing and Search
7

8
List and search contacts with comprehensive filtering options.
9

10
```python { .api }
11
def list_contacts(name: str = None, city: str = None, phone: str = None,
12
                 email: str = None, assigned_to: str = None,
13
                 limit: int = 10, offset: int = 0) -> dict:
14
    """
15
    List contacts with filtering and search.
16

17
    Args:
18
        name (str, optional): Filter by first or last name (partial match)
19
        city (str, optional): Filter by city
20
        phone (str, optional): Filter by phone number
21
        email (str, optional): Filter by email address
22
        assigned_to (str, optional): Filter by assigned user UUID
23
        limit (int): Number of results per page (default: 10)
24
        offset (int): Number of results to skip (default: 0)
25

26
    Returns:
27
        dict: Paginated contacts with metadata
28

29
    Headers Required:
30
        Authorization: Bearer <access_token>
31
        organization-id: <org_uuid>
32

33
    Example:
34
        GET /api/contacts/?name=john&city=new%20york&limit=5
35

36
        Response:
37
        {
38
            "count": 25,
39
            "next": "/api/contacts/?limit=5&offset=5",
40
            "previous": null,
41
            "results": [
42
                {
43
                    "id": "contact-uuid",
44
                    "first_name": "John",
45
                    "last_name": "Doe",
46
                    "primary_email": "john.doe@acme.com",
47
                    "mobile_number": "+1234567890",
48
                    "organization": "ACME Corporation",
49
                    "department": "Sales",
50
                    "address_line": "123 Main St",
51
                    "city": "New York",
52
                    "state": "NY",
53
                    "postcode": "10001",
54
                    "country": "USA",
55
                    "created_on": "2023-01-15T10:30:00Z",
56
                    "assigned_to": ["user1-uuid"],
57
                    "teams": ["team1-uuid"]
58
                }
59
            ]
60
        }
61
    """
62
```
63

64
### Contact Creation
65

66
Create new contacts with personal and organizational information.
67

68
```python { .api }
69
def create_contact(contact_data: dict) -> dict:
70
    """
71
    Create a new contact.
72

73
    Args:
74
        contact_data (dict): Contact information and associations
75

76
    Returns:
77
        dict: Created contact details
78

79
    Headers Required:
80
        Authorization: Bearer <access_token>
81
        organization-id: <org_uuid>
82
        Content-Type: multipart/form-data (if including attachments)
83

84
    Example:
85
        POST /api/contacts/
86
        {
87
            "first_name": "Jane",
88
            "last_name": "Smith",
89
            "primary_email": "jane.smith@client.com",
90
            "mobile_number": "+1987654321",
91
            "secondary_email": "j.smith@client.com",
92
            "organization": "Client Corp",
93
            "department": "Marketing",
94
            "designation": "Marketing Manager",
95
            "address_line": "456 Business Ave",
96
            "street": "Suite 200",
97
            "city": "Boston",
98
            "state": "MA",
99
            "postcode": "02101",
100
            "country": "USA",
101
            "assigned_to": ["user1-uuid"],
102
            "teams": ["team1-uuid"]
103
        }
104

105
        Response:
106
        {
107
            "id": "new-contact-uuid",
108
            "first_name": "Jane",
109
            "last_name": "Smith",
110
            ...contact details...
111
        }
112
    """
113
```
114

115
### Contact Details and Operations
116

117
Get comprehensive contact information and perform updates.
118

119
```python { .api }
120
def get_contact(pk: str) -> dict:
121
    """
122
    Get detailed contact information.
123

124
    Args:
125
        pk (str): Contact UUID
126

127
    Returns:
128
        dict: Complete contact details with related entities
129

130
    Headers Required:
131
        Authorization: Bearer <access_token>
132
        organization-id: <org_uuid>
133

134
    Example:
135
        GET /api/contacts/contact-uuid/
136

137
        Response:
138
        {
139
            "contact_obj": {
140
                "id": "contact-uuid",
141
                "first_name": "John",
142
                "last_name": "Doe",
143
                "primary_email": "john.doe@acme.com",
144
                "secondary_email": "j.doe@acme.com",
145
                "mobile_number": "+1234567890",
146
                "organization": "ACME Corporation",
147
                "department": "Sales",
148
                "designation": "Sales Director",
149
                "address_line": "123 Main St",
150
                "street": "Floor 5",
151
                "city": "New York",
152
                "state": "NY",
153
                "postcode": "10001",
154
                "country": "USA",
155
                "created_on": "2023-01-15T10:30:00Z",
156
                "created_by": "user-uuid"
157
            },
158
            "address_obj": {...address details...},
159
            "assigned_to": [...assigned users...],
160
            "teams": [...assigned teams...],
161
            "comments": [...contact comments...],
162
            "attachments": [...contact attachments...],
163
            "tasks": [...related tasks...],
164
            "users_mention": [...users for @mentions...]
165
        }
166
    """
167

168
def update_contact(pk: str, contact_data: dict) -> dict:
169
    """
170
    Update contact information.
171

172
    Args:
173
        pk (str): Contact UUID
174
        contact_data (dict): Updated contact information
175

176
    Returns:
177
        dict: Updated contact details
178

179
    Headers Required:
180
        Authorization: Bearer <access_token>
181
        organization-id: <org_uuid>
182

183
    Example:
184
        PUT /api/contacts/contact-uuid/
185
        {
186
            "first_name": "John",
187
            "last_name": "Doe",
188
            "mobile_number": "+1234567891",
189
            "department": "Senior Sales"
190
        }
191
    """
192

193
def delete_contact(pk: str) -> None:
194
    """
195
    Delete a contact.
196

197
    Args:
198
        pk (str): Contact UUID
199

200
    Returns:
201
        None: 204 No Content on success
202

203
    Headers Required:
204
        Authorization: Bearer <access_token>
205
        organization-id: <org_uuid>
206

207
    Example:
208
        DELETE /api/contacts/contact-uuid/
209
    """
210
```
211

212
### Contact Comments and Attachments
213

214
Manage comments and file attachments for contacts.
215

216
```python { .api }
217
def add_contact_comment_or_attachment(pk: str, comment: str = None,
218
                                    attachment: file = None) -> dict:
219
    """
220
    Add comment or attachment to contact.
221

222
    Args:
223
        pk (str): Contact UUID
224
        comment (str, optional): Comment text
225
        attachment (file, optional): File to attach
226

227
    Returns:
228
        dict: Success response
229

230
    Headers Required:
231
        Authorization: Bearer <access_token>
232
        organization-id: <org_uuid>
233
        Content-Type: multipart/form-data (for attachments)
234

235
    Example:
236
        POST /api/contacts/contact-uuid/
237
        {
238
            "comment": "Had great conversation about upcoming project"
239
        }
240
    """
241

242
def edit_contact_comment(pk: str, comment: str) -> dict:
243
    """
244
    Edit a contact comment.
245

246
    Args:
247
        pk (str): Comment UUID
248
        comment (str): Updated comment text
249

250
    Returns:
251
        dict: Updated comment
252

253
    Headers Required:
254
        Authorization: Bearer <access_token>
255

256
    Example:
257
        PUT /api/contacts/comment/comment-uuid/
258
        {
259
            "comment": "Updated comment text"
260
        }
261
    """
262

263
def delete_contact_comment(pk: str) -> None:
264
    """
265
    Delete a contact comment.
266

267
    Args:
268
        pk (str): Comment UUID
269

270
    Returns:
271
        None: 204 No Content on success
272

273
    Headers Required:
274
        Authorization: Bearer <access_token>
275

276
    Example:
277
        DELETE /api/contacts/comment/comment-uuid/
278
    """
279

280
def delete_contact_attachment(pk: str) -> None:
281
    """
282
    Delete a contact attachment.
283

284
    Args:
285
        pk (str): Attachment UUID
286

287
    Returns:
288
        None: 204 No Content on success
289

290
    Headers Required:
291
        Authorization: Bearer <access_token>
292

293
    Example:
294
        DELETE /api/contacts/attachment/attachment-uuid/
295
    """
296
```
297

298
## Contact Data Types
299

300
```python { .api }
301
class Contact:
302
    """Contact model representing an individual person"""
303
    id: str  # UUID
304
    first_name: str  # Required
305
    last_name: str  # Required
306
    primary_email: str  # Primary email address
307
    secondary_email: str  # Alternative email
308
    mobile_number: str  # Primary phone
309
    organization: str  # Company/organization name
310
    department: str  # Department within organization
311
    designation: str  # Job title/position
312

313
    # Address information
314
    address_line: str
315
    street: str  # Additional address line
316
    city: str
317
    state: str
318
    postcode: str
319
    country: str
320

321
    # Metadata
322
    created_on: datetime
323
    created_by: str  # User UUID
324
    org: str  # Organization UUID
325

326
    # Associations
327
    assigned_to: list[str]  # User UUIDs
328
    teams: list[str]  # Team UUIDs
329

330
class ContactComment:
331
    """Comments on contacts"""
332
    id: str  # UUID
333
    comment: str
334
    contact: str  # Contact UUID
335
    commented_on: datetime
336
    commented_by: str  # User UUID
337

338
class ContactAttachment:
339
    """File attachments on contacts"""
340
    id: str  # UUID
341
    attachment: str  # File path/URL
342
    contact: str  # Contact UUID
343
    created_on: datetime
344
    created_by: str  # User UUID
345
```
346

347
## Search and Filtering
348

349
Contacts support multiple search and filter options:
350

351
- **Name Search**: `name` parameter searches both first and last names (partial matching)
352
- **Location**: `city` filtering for geographic organization
353
- **Communication**: `phone` and `email` filtering
354
- **Assignment**: `assigned_to` filtering by user UUID
355
- **Organization**: Filter by company or department
356

357
All text-based filters support partial matching and are case-insensitive.
358

359
## Related Entities
360

361
Contacts can be associated with and participate in:
362
- **Accounts**: Primary company/organization relationships
363
- **Leads**: Contacts can be associated with sales leads
364
- **Opportunities**: Key stakeholders in sales deals
365
- **Tasks**: Work items assigned to or involving contacts
366
- **Events**: Meeting invitations and calendar events
367
- **Cases**: Support interactions and issue resolution
368
- **Comments**: Communication history and notes
369
- **Attachments**: Related documents and files
370

371
This makes contacts central to relationship management and communication tracking across the CRM system.