CRM Module - Document Management

Overview

The CRM (Customer Relationship Management) module provides comprehensive document management capabilities for all customer-facing entities. This guide covers document handling for five key CRM entities: Customers, Leads, Opportunities, Contacts, and Activities.

CRM Document Capabilities:

Customer KYC and compliance documents
Lead qualification and proposal documents
Opportunity contracts and negotiation materials
Contact business cards and correspondence
Activity meeting notes and recordings
Profile images for customers
Public and private document storage
Document tagging for workflow organization

Supported Entities

The CRM module supports document management for these entities:

Entity	Purpose	Common Document Types	Max File Size
Customer	Client records and contracts	Contracts, KYC, invoices, profile images	50 MB (5 MB for images)
Lead	Prospective customers	Proposals, specifications, quotes	20 MB
Opportunity	Sales deals in pipeline	Proposals, contracts, SOWs	50 MB
Contact	Individual contacts	Business cards, meeting notes	10 MB
Activity	Meetings, calls, tasks	Meeting notes, recordings, transcripts	100 MB

Customer Documents

Overview

Customer documents include contracts, KYC (Know Your Customer) documents, invoices, receipts, identity documents, and profile images. These documents are critical for compliance, customer service, and relationship management.

Endpoint: /api/v1/crm/customers/{customerId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`profile`	Customer profile images	Profile photo, avatar
`avatar`	Alternative to profile	Profile picture
`contract`	Service agreements	Annual contracts, MSA
`identity`	Identity verification	Driver's license, passport
`document`	General documents	Miscellaneous files
`kyc`	KYC compliance documents	Verification documents
`agreement`	Signed agreements	Service agreements, terms
`invoice`	Customer invoices	Sales invoices
`receipt`	Payment receipts	Payment confirmations

Common Scenarios

Scenario 1: Customer KYC Onboarding

Upload identity verification documents for new customer:

bash

# Upload driver's license
curl -X POST https://api.crm.test/api/v1/crm/customers/100001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@drivers_license.pdf" \
  -F "type=form" \
  -F "tags[]=identity" \
  -F "tags[]=kyc" \
  -F "name=Driver's License - John Doe" \
  -F "is_public=false" \
  -F "is_sensitive=true" \
  -F "expires_at=2030-08-15T23:59:59Z"

# Upload proof of address
curl -X POST https://api.crm.test/api/v1/crm/customers/100001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@utility_bill.pdf" \
  -F "type=form" \
  -F "tags[]=kyc" \
  -F "tags[]=document" \
  -F "name=Proof of Address - Utility Bill" \
  -F "is_public=false" \
  -F "is_sensitive=true"

# Retrieve all KYC documents
curl -X GET "https://api.crm.test/api/v1/crm/customers/100001/documents?tags=kyc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Scenario 2: Service Contract Management

Upload and manage customer service contracts:

bash

# Upload new service contract
curl -X POST https://api.crm.test/api/v1/crm/customers/100001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@service_contract_2025.pdf" \
  -F "type=contract" \
  -F "tags[]=contract" \
  -F "tags[]=agreement" \
  -F "name=Service Contract 2025" \
  -F "description=Annual premium support agreement" \
  -F "is_public=false" \
  -F "is_sensitive=true" \
  -F "expires_at=2025-12-31T23:59:59Z"

# List all customer contracts
curl -X GET "https://api.crm.test/api/v1/crm/customers/100001/documents?type=contract" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Scenario 3: Customer Profile Image

Upload and manage customer profile images:

bash

# Upload profile image
curl -X POST https://api.crm.test/api/v1/crm/customers/100001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@profile_photo.jpg" \
  -F "type=image" \
  -F "tags[]=profile" \
  -F "tags[]=avatar" \
  -F "name=John Doe Profile Image" \
  -F "is_public=true" \
  -F "width=1024" \
  -F "height=1024"

Validation Rules

File Requirements:

Maximum size: 50 MB (general documents), 5 MB (profile images)
Profile images: JPEG, PNG, GIF, WebP
Profile image dimensions: 200x200 to 4000x4000 pixels
All other file types accepted

Required Fields:

file - The document file
type - Document type (from DocumentType enum)

Optional Fields:

tags - Array of tags (validated against allowed list)
name - Custom document name
description - Document description
is_public - Public visibility (default: false, true for profile images)
is_sensitive - Sensitive data flag
expires_at - Expiration date

Lead Documents

Overview

Lead documents include proposals, specifications, quotes, brochures, and qualification documents. These documents support the lead nurturing and qualification process.

Endpoint: /api/v1/crm/leads/{leadId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`inquiry`	Initial inquiries	Customer inquiry forms
`proposal`	Business proposals	Sales proposals
`quote`	Price quotations	Pricing documents
`brochure`	Marketing materials	Product brochures
`specification`	Technical specs	Product specifications
`presentation`	Sales presentations	Demo presentations
`correspondence`	Email/letter correspondence	Communication history
`qualification_document`	Lead qualification	Qualification forms
`rfp`	Request for Proposal	RFP documents
`rfq`	Request for Quote	RFQ documents

Common Scenarios

Scenario 1: Lead Qualification with RFP

Handle RFP (Request for Proposal) documents:

bash

# Upload received RFP document
curl -X POST https://api.crm.test/api/v1/crm/leads/200001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@customer_rfp.pdf" \
  -F "type=proposal" \
  -F "tags[]=rfp" \
  -F "tags[]=qualification_document" \
  -F "name=RFP - Enterprise Software Solution" \
  -F "description=Customer RFP received via email" \
  -F "is_public=false"

# Upload RFP response proposal
curl -X POST https://api.crm.test/api/v1/crm/leads/200001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@rfp_response.pdf" \
  -F "type=proposal" \
  -F "tags[]=proposal" \
  -F "tags[]=rfp_response" \
  -F "name=RFP Response - Our Solution" \
  -F "is_public=false"

Scenario 2: Lead Nurturing with Marketing Materials

Share marketing materials with lead:

bash

# Upload product brochure
curl -X POST https://api.crm.test/api/v1/crm/leads/200001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@product_brochure.pdf" \
  -F "type=marketing" \
  -F "tags[]=brochure" \
  -F "name=Product Brochure 2025" \
  -F "is_public=true"

# Upload presentation
curl -X POST https://api.crm.test/api/v1/crm/leads/200001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@demo_presentation.pptx" \
  -F "type=presentation" \
  -F "tags[]=presentation" \
  -F "name=Product Demo Presentation" \
  -F "is_public=false"

Validation Rules

File Requirements:

Maximum size: 20 MB
All file types accepted

Required Fields:

file - The document file
type - Document type

Optional Fields:

tags - Array of tags (validated against allowed list)
name, description, is_public, is_sensitive

Opportunity Documents

Overview

Opportunity documents include proposals, contracts, SOWs (Statement of Work), quotes, and negotiation materials. These documents are critical for managing sales pipeline and closing deals.

Endpoint: /api/v1/crm/opportunities/{opportunityId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`proposal`	Sales proposals	Final proposal documents
`contract`	Sales contracts	Contract documents
`quote`	Price quotes	Pricing quotations
`sow`	Statement of Work	Project scope documents
`presentation`	Sales presentations	Pitch presentations
`rfp_response`	RFP responses	Proposal responses
`negotiation`	Negotiation documents	Terms negotiation
`terms`	Terms and conditions	T&C documents
`msa`	Master Service Agreement	MSA documents
`nda`	Non-Disclosure Agreement	Confidentiality agreements
`amendment`	Contract amendments	Contract modifications

Common Scenarios

Scenario 1: Deal Closure with Contract

Upload contract documents for opportunity closure:

bash

# Upload signed MSA
curl -X POST https://api.crm.test/api/v1/crm/opportunities/300001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@msa_signed.pdf" \
  -F "type=contract" \
  -F "tags[]=msa" \
  -F "tags[]=contract" \
  -F "name=Master Service Agreement - Signed" \
  -F "description=Fully executed MSA" \
  -F "is_public=false" \
  -F "is_sensitive=true"

# Upload SOW
curl -X POST https://api.crm.test/api/v1/crm/opportunities/300001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@sow_project.pdf" \
  -F "type=contract" \
  -F "tags[]=sow" \
  -F "name=Statement of Work - Q1 2025 Project" \
  -F "is_public=false" \
  -F "is_sensitive=true"

Scenario 2: Proposal Workflow

Manage proposal documents through sales cycle:

bash

# Upload initial proposal
curl -X POST https://api.crm.test/api/v1/crm/opportunities/300001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@proposal_v1.pdf" \
  -F "type=proposal" \
  -F "tags[]=proposal" \
  -F "name=Initial Proposal v1.0" \
  -F "is_public=false"

# Upload revised proposal after negotiation
curl -X POST https://api.crm.test/api/v1/crm/opportunities/300001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@proposal_v2.pdf" \
  -F "type=proposal" \
  -F "tags[]=proposal" \
  -F "tags[]=negotiation" \
  -F "name=Revised Proposal v2.0" \
  -F "description=Updated pricing and terms after negotiation" \
  -F "is_public=false"

# List all proposal versions
curl -X GET "https://api.crm.test/api/v1/crm/opportunities/300001/documents?tags=proposal&include_archived=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Validation Rules

File Requirements:

Maximum size: 50 MB
All file types accepted

Required Fields:

file, type

Optional Fields:

tags, name, description, is_public, is_sensitive

Contact Documents

Overview

Contact documents include business cards, meeting notes, correspondence, NDAs, and resumes. These documents help maintain detailed records of individual contacts within customer organizations.

Endpoint: /api/v1/crm/contacts/{contactId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`business_card`	Business cards	Scanned business cards
`meeting_notes`	Meeting notes	Notes from meetings
`correspondence`	Email/letter correspondence	Communication history
`agreement`	Signed agreements	Agreement documents
`nda`	Non-Disclosure Agreement	Confidentiality agreements
`reference`	Reference materials	Reference documents
`resume`	CV/Resume	Contact's resume
`introduction`	Introduction emails	Initial contact documents
`linkedin_profile`	LinkedIn profile exports	Social profile data

Common Scenarios

Scenario 1: Business Card Management

Scan and store business cards:

bash

# Upload scanned business card
curl -X POST https://api.crm.test/api/v1/crm/contacts/400001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@business_card.jpg" \
  -F "type=image" \
  -F "tags[]=business_card" \
  -F "name=Business Card - Sarah Johnson" \
  -F "is_public=false"

Scenario 2: Meeting Documentation

Store meeting notes and correspondence:

bash

# Upload meeting notes
curl -X POST https://api.crm.test/api/v1/crm/contacts/400001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@meeting_notes.pdf" \
  -F "type=report" \
  -F "tags[]=meeting_notes" \
  -F "name=Meeting Notes - Q1 Review" \
  -F "description=Quarterly business review meeting" \
  -F "is_public=false"

# Upload correspondence
curl -X POST https://api.crm.test/api/v1/crm/contacts/400001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@email_thread.pdf" \
  -F "type=other" \
  -F "tags[]=correspondence" \
  -F "name=Email Thread - Project Requirements" \
  -F "is_public=false"

Validation Rules

File Requirements:

Maximum size: 10 MB
All file types accepted

Required Fields:

file, type

Optional Fields:

tags, name, description, is_public, is_sensitive

Activity Documents

Overview

Activity documents include meeting agendas, minutes, presentations, recordings, transcripts, and action items. Activities represent meetings, calls, tasks, and emails, and documents provide context and record-keeping.

Endpoint: /api/v1/crm/activities/{activityId}/documents

Supported Tags

Tag	Purpose	Example Use Case
`meeting_notes`	Meeting notes	Notes from meetings
`agenda`	Meeting agendas	Agenda documents
`minutes`	Meeting minutes	Formal meeting minutes
`presentation`	Presentations used	Slide decks
`recording`	Audio/video recordings	Meeting recordings
`transcript`	Meeting transcripts	Transcribed meetings
`attachment`	Email attachments	Files attached to emails
`follow_up`	Follow-up documents	Action item documents
`action_items`	Action item lists	Task lists
`screenshot`	Screenshots	Screen captures

Common Scenarios

Scenario 1: Meeting Documentation

Complete meeting documentation workflow:

bash

# Upload meeting agenda (before meeting)
curl -X POST https://api.crm.test/api/v1/crm/activities/500001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@agenda.pdf" \
  -F "type=report" \
  -F "tags[]=agenda" \
  -F "name=Meeting Agenda - Q1 Planning" \
  -F "is_public=false"

# Upload presentation used in meeting
curl -X POST https://api.crm.test/api/v1/crm/activities/500001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@presentation.pptx" \
  -F "type=presentation" \
  -F "tags[]=presentation" \
  -F "name=Q1 Strategy Presentation" \
  -F "is_public=false"

# Upload meeting recording (after meeting)
curl -X POST https://api.crm.test/api/v1/crm/activities/500001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@recording.mp4" \
  -F "type=video" \
  -F "tags[]=recording" \
  -F "name=Meeting Recording - Q1 Planning Session" \
  -F "is_public=false"

# Upload meeting minutes
curl -X POST https://api.crm.test/api/v1/crm/activities/500001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@minutes.pdf" \
  -F "type=report" \
  -F "tags[]=minutes" \
  -F "tags[]=meeting_notes" \
  -F "name=Meeting Minutes - Q1 Planning" \
  -F "is_public=false"

# Upload action items
curl -X POST https://api.crm.test/api/v1/crm/activities/500001/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@action_items.pdf" \
  -F "type=report" \
  -F "tags[]=action_items" \
  -F "tags[]=follow_up" \
  -F "name=Action Items - Q1 Planning" \
  -F "is_public=false"

Scenario 2: Email Activity with Attachments

Store email attachments with email activity:

bash

# Upload email attachments
curl -X POST https://api.crm.test/api/v1/crm/activities/500002/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@attachment.pdf" \
  -F "type=other" \
  -F "tags[]=attachment" \
  -F "name=Email Attachment - Contract Draft" \
  -F "description=Attached to email from customer" \
  -F "is_public=false"

Validation Rules

File Requirements:

Maximum size: 100 MB (larger limit for recordings)
All file types accepted
Supports video and audio files for recordings

Required Fields:

file, type

Optional Fields:

tags, name, description, is_public

Cross-Entity Document Workflows

Lead to Customer Conversion

When converting a lead to a customer, documents should be transferred:

bash

# 1. Retrieve all lead documents
GET /api/v1/crm/leads/200001/documents

# 2. Convert lead to customer (returns customer ID)
POST /api/v1/crm/leads/200001/convert

# 3. Re-upload critical documents to customer record
# (Documents remain attached to archived lead for history)
POST /api/v1/crm/customers/100050/documents

Opportunity to Order Workflow

Link opportunity documents to sales orders:

bash

# 1. Get signed contract from opportunity
GET /api/v1/crm/opportunities/300001/documents?tags=contract

# 2. Create sales order from opportunity
POST /api/v1/sales/orders

# 3. Attach contract to sales order (if needed)
POST /api/v1/sales/orders/80001/documents

Best Practices

1. Document Organization

Use Consistent Tagging:

Apply standard tags for similar document types
Combine generic and specific tags (e.g., contract + msa)
Use tags that match your business workflows

Name Documents Clearly:

Include entity name, document type, and version
Example: "Service Agreement 2025 - Acme Corp v2.0"
Use dates when relevant

2. Security and Compliance

Mark Sensitive Documents:

Always set is_sensitive: true for contracts, KYC, personal data
Restrict access to authorized users only
Comply with data protection regulations (GDPR, CCPA)

Set Expiration Dates:

Use for time-limited documents (IDs, certifications)
System can flag expired documents for review
Required for compliance tracking

3. Workflow Integration

Document at Each Stage:

Lead Stage: Proposals, specs, quotes
Opportunity Stage: Contracts, SOWs, NDAs
Customer Stage: Executed contracts, KYC, invoices
Activity Stage: Meeting notes, recordings, action items

Maintain Document History:

Don't delete old versions (system archives automatically)
Retrieve history with include_archived=true
Useful for audit trail and reference

4. Performance Optimization

File Size Management:

Compress large files before upload
Use appropriate formats (PDF for documents, WebP for images)
Consider file size limits per entity type

Public vs Private Storage:

Use public storage for marketing materials
Keep customer data, contracts private
Improves performance for public assets

Troubleshooting

Common Issues

Problem: Upload fails with "Invalid tag" error

Solution:

Check that tags match the allowed list for entity type
Refer to Supported Tags section for each entity
Tags are entity-specific (customer tags differ from lead tags)

Problem: Document not visible in list

Solution:

Check filter parameters (type, tags)
Verify document wasn't archived
Use include_archived=true to see all documents

Problem: Cannot download document

Solution:

Confirm user has permission on parent entity
Check that document file exists in storage
Verify authentication token is valid

Main Document Management Guide - System-wide documentation
Customer Management - Complete customer documentation
Lead Management - Lead management workflows
Opportunity Pipeline - Opportunity management

API Reference

For complete API specifications:

OpenAPI Specification: /docs/openapi.yaml
Interactive Documentation: Scribe-generated API docs
Endpoint Group: CRM Module → Document Management

CRM Module - Document Management ​

Overview ​

Supported Entities ​

Customer Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Customer KYC Onboarding ​

Scenario 2: Service Contract Management ​

Scenario 3: Customer Profile Image ​

Validation Rules ​

Lead Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Lead Qualification with RFP ​

Scenario 2: Lead Nurturing with Marketing Materials ​

Validation Rules ​

Opportunity Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Deal Closure with Contract ​

Scenario 2: Proposal Workflow ​

Validation Rules ​

Contact Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Business Card Management ​

Scenario 2: Meeting Documentation ​

Validation Rules ​

Activity Documents ​

Overview ​

Supported Tags ​

Common Scenarios ​

Scenario 1: Meeting Documentation ​

Scenario 2: Email Activity with Attachments ​

Validation Rules ​

Cross-Entity Document Workflows ​

Lead to Customer Conversion ​

Opportunity to Order Workflow ​

Best Practices ​

1. Document Organization ​

2. Security and Compliance ​

3. Workflow Integration ​

4. Performance Optimization ​

Troubleshooting ​

Common Issues ​

Related Documentation ​

API Reference ​

CRM Module - Document Management

Overview

Supported Entities

Customer Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Customer KYC Onboarding

Scenario 2: Service Contract Management

Scenario 3: Customer Profile Image

Validation Rules

Lead Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Lead Qualification with RFP

Scenario 2: Lead Nurturing with Marketing Materials

Validation Rules

Opportunity Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Deal Closure with Contract

Scenario 2: Proposal Workflow

Validation Rules

Contact Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Business Card Management

Scenario 2: Meeting Documentation

Validation Rules

Activity Documents

Overview

Supported Tags

Common Scenarios

Scenario 1: Meeting Documentation

Scenario 2: Email Activity with Attachments

Validation Rules

Cross-Entity Document Workflows

Lead to Customer Conversion

Opportunity to Order Workflow

Best Practices

1. Document Organization

2. Security and Compliance

3. Workflow Integration

4. Performance Optimization

Troubleshooting

Common Issues

Related Documentation

API Reference