0
# Contact & Organization Management
1

2
Comprehensive contact and organization management with relationship tracking, custom fields, address management, and communication history. This module forms the core of CRM functionality by managing people and companies.
3

4
## Capabilities
5

6
### Contact Management
7

8
Individual contact entities with personal information and relationship tracking.
9

10
```python { .api }
11
class Contact(CremeEntity):
12
    """
13
    Individual contact entity with personal and professional information.
14

15
    Attributes:
16
    - civility: ForeignKey, title/salutation (Mr., Ms., Dr., etc.)
17
    - first_name: str, given name
18
    - last_name: str, family name
19
    - description: str, additional notes
20
    - position: ForeignKey, job position
21
    - is_a_nerd: bool, technical person flag
22
    - birthday: DateField, date of birth
23
    - image: ImageField, profile photo
24
    - skype: str, Skype username
25
    - phone: str, primary phone number
26
    - mobile: str, mobile phone number
27
    - email: str, primary email address
28
    - url_site: URLField, personal website
29
    - sector: ForeignKey, industry sector
30
    - language: ForeignKey, preferred language
31

32
    Methods:
33
    - get_absolute_url(): Get contact detail URL
34
    - get_pretty_address(): Format complete address
35
    - get_employers(): Get organizations this contact works for
36
    - get_managers(): Get contacts who manage this contact
37
    - get_teammates(): Get colleagues at same organization
38
    - get_contact_summary(): Get formatted contact information
39
    """
40

41
def get_contact_model():
42
    """
43
    Get the active Contact model class from settings.
44

45
    Returns:
46
    type[Contact]: The configured contact model class
47

48
    Example:
49
    ContactModel = get_contact_model()
50
    contact = ContactModel.objects.create(
51
        first_name="John",
52
        last_name="Doe",
53
        email="john@example.com"
54
    )
55
    """
56
```
57

58
### Organization Management
59

60
Company and organization entities with business information and contact relationships.
61

62
```python { .api }
63
class Organisation(CremeEntity):
64
    """
65
    Company/organization entity with business information.
66

67
    Attributes:
68
    - name: str, organization name
69
    - is_managed: bool, whether organization is actively managed
70
    - staff_size: int, number of employees
71
    - capital: PositiveIntegerField, company capital
72
    - siren: str, French SIREN number
73
    - naf: str, French NAF code
74
    - siret: str, French SIRET number
75
    - rcs: str, French RCS number
76
    - tvaintra: str, EU VAT number
77
    - subject_to_vat: bool, VAT registration status
78
    - annual_revenue: PositiveIntegerField, yearly revenue
79
    - description: str, company description
80
    - phone: str, main phone number
81
    - fax: str, fax number
82
    - email: str, primary email address
83
    - url_site: URLField, company website
84
    - sector: ForeignKey, industry sector
85
    - legal_form: ForeignKey, legal structure
86
    - creation_date: DateField, company founding date
87
    - image: ImageField, company logo
88

89
    Methods:
90
    - get_absolute_url(): Get organization detail URL
91
    - get_pretty_address(): Format complete address
92
    - get_employees(): Get contacts who work for this organization
93
    - get_managers(): Get management contacts
94
    - get_subsidiaries(): Get subsidiary organizations
95
    - get_parent_orga(): Get parent organization
96
    - get_customers(): Get customer organizations
97
    - get_suppliers(): Get supplier organizations
98
    """
99

100
def get_organisation_model():
101
    """
102
    Get the active Organisation model class from settings.
103

104
    Returns:
105
    type[Organisation]: The configured organisation model class
106

107
    Example:
108
    OrganisationModel = get_organisation_model()
109
    org = OrganisationModel.objects.create(
110
        name="Example Corp",
111
        email="info@example.com",
112
        phone="+1-555-0123"
113
    )
114
    """
115
```
116

117
### Address Management
118

119
Address storage and management with geolocation support.
120

121
```python { .api }
122
class Address(CremeModel):
123
    """
124
    Address information for contacts and organizations.
125

126
    Attributes:
127
    - name: str, address label/name
128
    - address: str, street address
129
    - po_box: str, post office box
130
    - zipcode: str, postal code
131
    - city: str, city name
132
    - department: str, department/state
133
    - country: str, country name
134
    - latitude: DecimalField, GPS latitude
135
    - longitude: DecimalField, GPS longitude
136
    - content_type: ContentType, entity type this address belongs to
137
    - object_id: int, entity ID this address belongs to
138

139
    Methods:
140
    - get_pretty_address(): Format complete address string
141
    - __str__(): String representation of address
142
    - geocode(): Update latitude/longitude coordinates
143
    """
144
```
145

146
### Contact Information Types
147

148
Supporting models for contact categorization and organization.
149

150
```python { .api }
151
class Civility(CremeModel):
152
    """
153
    Title/salutation options for contacts.
154

155
    Attributes:
156
    - title: str, title text (Mr., Ms., Dr., Prof., etc.)
157
    - shortcut: str, abbreviated form
158

159
    Methods:
160
    - __str__(): Return title text
161
    """
162

163
class Position(CremeModel):
164
    """
165
    Job positions and roles.
166

167
    Attributes:
168
    - title: str, position title
169
    - description: str, position description
170

171
    Methods:
172
    - __str__(): Return position title
173
    """
174

175
class Sector(CremeModel):
176
    """
177
    Industry sectors for categorizing contacts and organizations.
178

179
    Attributes:
180
    - title: str, sector name
181
    - order: int, display order
182

183
    Methods:
184
    - __str__(): Return sector title
185
    """
186

187
class LegalForm(CremeModel):
188
    """
189
    Legal forms/structures for organizations.
190

191
    Attributes:
192
    - title: str, legal form name
193
    - shortcut: str, abbreviated form
194

195
    Methods:
196
    - __str__(): Return legal form title
197
    """
198
```
199

200
### Staff Size Categories
201

202
Employee count categorization for organizations.
203

204
```python { .api }
205
class StaffSize(CremeModel):
206
    """
207
    Staff size categories for organizations.
208

209
    Attributes:
210
    - size: str, size category description
211
    - order: int, display order
212

213
    Methods:
214
    - __str__(): Return size description
215

216
    Common Values:
217
    - "1-10 employees"
218
    - "11-50 employees"
219
    - "51-200 employees"
220
    - "201-1000 employees"
221
    - "1000+ employees"
222
    """
223
```
224

225
## Usage Examples
226

227
### Creating Contacts
228

229
```python
230
from creme.persons import get_contact_model
231

232
ContactModel = get_contact_model()
233

234
# Create a basic contact
235
contact = ContactModel.objects.create(
236
    first_name="John",
237
    last_name="Doe",
238
    email="john@example.com",
239
    phone="+1-555-0123"
240
)
241

242
# Create contact with full information
243
from creme.persons.models import Civility, Position, Sector
244

245
mr_civility = Civility.objects.get(title="Mr.")
246
ceo_position = Position.objects.get(title="CEO")
247
tech_sector = Sector.objects.get(title="Technology")
248

249
contact = ContactModel.objects.create(
250
    civility=mr_civility,
251
    first_name="Jane",
252
    last_name="Smith",
253
    email="jane.smith@techcorp.com",
254
    phone="+1-555-0456",
255
    mobile="+1-555-0789",
256
    position=ceo_position,
257
    sector=tech_sector,
258
    is_a_nerd=True,
259
    birthday=datetime.date(1980, 5, 15)
260
)
261
```
262

263
### Creating Organizations
264

265
```python
266
from creme.persons import get_organisation_model
267

268
OrganisationModel = get_organisation_model()
269

270
# Create a basic organization
271
org = OrganisationModel.objects.create(
272
    name="Tech Solutions Inc.",
273
    email="info@techsolutions.com",
274
    phone="+1-555-0100",
275
    url_site="https://www.techsolutions.com"
276
)
277

278
# Create organization with detailed information
279
from creme.persons.models import LegalForm, StaffSize
280

281
llc_form = LegalForm.objects.get(title="LLC")
282
medium_size = StaffSize.objects.get(size="51-200 employees")
283

284
org = OrganisationModel.objects.create(
285
    name="Innovation Corp",
286
    email="contact@innovation.com",
287
    phone="+1-555-0200",
288
    legal_form=llc_form,
289
    staff_size=medium_size,
290
    sector=tech_sector,
291
    annual_revenue=5000000,
292
    capital=1000000,
293
    subject_to_vat=True,
294
    creation_date=datetime.date(2010, 1, 15)
295
)
296
```
297

298
### Adding Addresses
299

300
```python
301
from creme.persons.models import Address
302
from django.contrib.contenttypes.models import ContentType
303

304
# Add address to contact
305
contact_ct = ContentType.objects.get_for_model(ContactModel)
306
address = Address.objects.create(
307
    name="Home",
308
    address="123 Main Street",
309
    city="New York",
310
    zipcode="10001",
311
    country="USA",
312
    content_type=contact_ct,
313
    object_id=contact.id
314
)
315

316
# Add address to organization
317
org_ct = ContentType.objects.get_for_model(OrganisationModel)
318
office_address = Address.objects.create(
319
    name="Head Office",
320
    address="456 Business Plaza",
321
    city="San Francisco",
322
    zipcode="94105",
323
    country="USA",
324
    content_type=org_ct,
325
    object_id=org.id
326
)
327
```
328

329
### Creating Relationships
330

331
```python
332
from creme.creme_core.models import Relation, RelationType
333

334
# Create employment relationship
335
employed_rel = RelationType.objects.get(pk='persons-subject_employed_by')
336
Relation.objects.create(
337
    user=request.user,
338
    subject_entity=contact,
339
    object_entity=org,
340
    type=employed_rel
341
)
342

343
# Create management relationship
344
manages_rel = RelationType.objects.get(pk='persons-subject_manages')
345
Relation.objects.create(
346
    user=request.user,
347
    subject_entity=manager_contact,
348
    object_entity=employee_contact,
349
    type=manages_rel
350
)
351

352
# Create customer relationship
353
customer_rel = RelationType.objects.get(pk='persons-subject_customer_supplier')
354
Relation.objects.create(
355
    user=request.user,
356
    subject_entity=customer_org,
357
    object_entity=supplier_org,
358
    type=customer_rel
359
)
360
```
361

362
### Querying Contacts and Organizations
363

364
```python
365
# Find contacts by criteria
366
tech_contacts = ContactModel.objects.filter(
367
    sector__title="Technology",
368
    is_a_nerd=True
369
)
370

371
# Find organizations by size
372
large_orgs = OrganisationModel.objects.filter(
373
    staff_size__size__contains="1000+"
374
)
375

376
# Find contacts at specific organization
377
org_employees = ContactModel.objects.filter(
378
    relations_as_subject__type__pk='persons-subject_employed_by',
379
    relations_as_subject__object_entity=org
380
)
381

382
# Find organization's customers
383
customers = OrganisationModel.objects.filter(
384
    relations_as_object__type__pk='persons-subject_customer_supplier',
385
    relations_as_object__subject_entity=org
386
)
387

388
# Search contacts by name
389
matching_contacts = ContactModel.objects.filter(
390
    models.Q(first_name__icontains="John") |
391
    models.Q(last_name__icontains="John")
392
)
393
```
394

395
### Address and Location Features
396

397
```python
398
# Get formatted addresses
399
contact_address = contact.get_pretty_address()
400
print(f"Contact address: {contact_address}")
401

402
# Geocode addresses (requires geolocation module)
403
if address.latitude is None:
404
    address.geocode()  # Updates latitude/longitude
405
    address.save()
406

407
# Find nearby contacts (requires geolocation calculations)
408
from django.db.models import Q
409
import math
410

411
def find_nearby_contacts(center_lat, center_lng, radius_km=10):
412
    """Find contacts within radius of coordinates."""
413
    # Approximate degree conversion (rough calculation)
414
    lat_range = radius_km / 111.0  # ~111km per degree latitude
415
    lng_range = radius_km / (111.0 * math.cos(math.radians(center_lat)))
416

417
    return ContactModel.objects.filter(
418
        addresses__latitude__range=(center_lat - lat_range, center_lat + lat_range),
419
        addresses__longitude__range=(center_lng - lng_range, center_lng + lng_range)
420
    ).distinct()
421
```
422

423
## Integration with Other Modules
424

425
The contact and organization system integrates with all other CRM modules:
426

427
- **Activities**: Schedule meetings, calls, and tasks with contacts
428
- **Opportunities**: Track sales opportunities with organizations
429
- **Billing**: Generate invoices for customers
430
- **Documents**: Attach files to contacts and organizations
431
- **Emails**: Send campaigns to mailing lists
432
- **Commercial**: Track sales activities and approaches
433
- **Projects**: Assign contacts to project teams
434
- **Tickets**: Create support tickets for customers