Introduction
In Odoo, models define how data is structured and stored in the database. Every piece of business data you work with, from sales orders to invoices to leads, lives in a model.
Understanding Odoo models is essential for both developers and functional consultants. Models are the foundation of the Odoo data architecture. They define Odoo fields, relationships, and business logic.
This article focuses on the crm.lead model. It powers the sales pipeline in Odoo CRM. Whether you are building custom modules, integrating external systems, or configuring sales workflows, you will work with this model.
What is the crm.lead Model
The crm.lead model represents leads and opportunities in Odoo. It is the central place where sales pipeline data is stored. A single model in Odoo handles both early-stage leads and qualified opportunities.
This model is used by the CRM module. Sales, marketing, and website modules extend or reference it. When a visitor fills a form on your website, when a salesperson creates an opportunity, or when a lead is converted to a customer, you are working with crm.lead.
The model uses Odoo model inheritance to add functionality. The base CRM module defines the core structure. Other modules like crm_iap_lead_enrich or website_crm add fields and behavior. Each module extends what it needs without duplicating the core.
Key Fields in the Model
Here are the most important Odoo fields in the crm.lead model. Understanding these will help you work effectively with leads and opportunities.
1. name
Type: Char. This field stores the name or title of the lead or opportunity. It is the main identifier shown in list views and kanban. For a lead, it might be "Inquiry from website." For an opportunity, it could be "Enterprise deal - Acme Corp."
2. contact_name
Type: Char. The name of the contact person. Used when the lead is not yet linked to a res.partner. When you convert a lead, this value is often copied to the new partner record.
3. email_from
Type: Char. The primary email address of the lead. Odoo uses this for communications before conversion. It is the main way to identify and deduplicate leads.
4. phone
Type: Char. The main phone number. Displayed on the lead form and used for call logging and follow-up activities.
5. mobile
Type: Char. Mobile phone number. Often used for SMS or urgent follow-up when different from the main phone.
6. partner_id
Type: Many2one (res.partner). Links to the contact or company when the lead is qualified or converted. Before conversion, this field is empty. After conversion, it links to the created or matched partner.
7. user_id
Type: Many2one (res.users). The salesperson responsible for the lead. Used for assignment, reporting, and activity scheduling. Drives the "My Opportunities" and team dashboards.
8. team_id
Type: Many2one (crm.team). The sales team. Organizes leads by team for round-robin assignment and team-based reporting.
9. stage_id
Type: Many2one (crm.stage). The current stage in the pipeline. Stages define the funnel: New, Qualified, Proposal, Negotiation, Won, Lost. Moving between stages drives automation and reporting.
10. type
Type: Selection. Indicates whether the record is a Lead or an Opportunity. Leads are early-stage. Opportunities are qualified and have expected revenue. The type affects which views and stages are available.
11. expected_revenue
Type: Float. The expected revenue if the opportunity is won. Used for pipeline value reporting and forecasting. Often computed from probability and a deal amount.
12. probability
Type: Float. The win probability as a percentage (0 to 100). Used in weighted pipeline calculations. Can be manual or automated based on stage.
13. company_id
Type: Many2one (res.company). In multi-company setups, this indicates which Odoo company the lead belongs to. Affects record visibility and currency.
14. description
Type: Text. Notes and description of the lead or opportunity. Used for internal notes, meeting summaries, and context that salespeople need when following up.
15. create_date
Type: Datetime. Stores the date and time when the record was created. Automatically managed by Odoo. Useful for lead age reporting and conversion time analysis.
16. write_date
Type: Datetime. Stores the date and time of the last modification. Also automatically managed. Helps track when the lead was last updated.
17. date_open
Type: Datetime. When the lead was first assigned to a user. Set when user_id is filled. Used to measure time-to-first-contact and assignment speed.
18. date_closed
Type: Datetime. When the lead was closed (won or lost). Set when the stage moves to a closed stage. Used for conversion analysis and sales cycle length.
19. date_deadline
Type: Date. The expected closing date. Used for forecasting and activity planning. Salespeople set this to track when they expect to close the deal.
20. active
Type: Boolean. Soft delete flag. When False, the record is archived and hidden from default views. Lost or merged leads are often archived rather than deleted.
21. street, street2, city, zip
Type: Char. Address fields. Used when the lead has an address before conversion. Copied to the partner when the lead is converted.
22. country_id
Type: Many2one (res.country). The country. Used for regional reporting and address formatting. Filtering leads by country helps with territory management.
23. state_id
Type: Many2one (res.country.state). The state or province. The domain is filtered by country. Used for regional segmentation.
24. source_id
Type: Many2one (utm.source). The lead source. Tracks where the lead came from: Website, Referral, Campaign, etc. Important for marketing attribution.
25. campaign_id
Type: Many2one (utm.campaign). The marketing campaign. Links the lead to a specific campaign for ROI analysis. Used when leads come from email or ad campaigns.
26. activity_ids
Type: One2many (mail.activity). The scheduled activities. Tasks, calls, and meetings linked to the lead. Drives the activity widget and follow-up reminders.
27. color
Type: Integer. Color index for kanban and list views. Used to visually distinguish leads by priority, source, or custom criteria.
28. message_ids
Type: One2many (mail.message). The chatter. Internal notes, emails, and activity history. Odoo stores all communication in the chatter for full context.
How This Model Is Used in Business Workflows
1. Website Lead Capture
When a visitor submits a contact form on your Odoo website, a new crm.lead record is created. The email_from, contact_name, and description are filled from the form. The lead appears in the CRM pipeline for the sales team to follow up.
2. Lead Qualification and Conversion
Salespeople move leads through stages. When a lead is qualified, they change the type to Opportunity and set expected_revenue. When the deal is won, they convert the lead. Odoo creates or links a res.partner and optionally a sale.order.
3. Sales Pipeline Reporting
Managers use crm.lead data for pipeline reports. Expected revenue, probability, and stage drive weighted pipeline value. Filters by user_id and team_id show performance by salesperson and team.
4. Marketing Attribution
The source_id and campaign_id fields link leads to marketing efforts. When leads come from email campaigns or ads, UTM parameters populate these fields. Marketing teams use this to measure campaign effectiveness.
5. Activity and Follow-up Management
Salespeople schedule activities on leads. The activity_ids field stores calls, meetings, and tasks. The activity_date_deadline drives the "Next Activity" column in list views and reminds users to follow up.
How Developers Extend This Model
Developers extend crm.lead using several patterns. Odoo model inheritance is the main mechanism.
Model Inheritance
Use _inherit = 'crm.lead' to extend the model. Add new Odoo fields, override methods, or add constraints. The inherit model in Odoo keeps your changes in a separate module for easy upgrades.
Adding Fields
Define new Odoo fields in your inherited model. Use the right field type: Char, Many2one, Boolean, Integer, Text, Selection. Common additions include custom lead sources, product interest, or industry. Consider company-dependent fields for multi-company.
Python Extensions
Override create, write, or the action_convert method to add logic. Use super() to call the original. Be careful with stage changes and conversion logic. The api model in Odoo decorators (@api.depends, @api.onchange) help with computed fields and UI behavior.
Odoo Studio
Odoo Studio lets you add fields without code. Good for quick customizations like extra dropdowns or text fields. For complex logic, stage automation, or upgrades, custom modules are more maintainable.
Best Practices
- Configure stages to match your sales process. Use separate stage sequences for leads and opportunities if needed.
- Set source_id and campaign_id from UTM parameters on website forms. This enables marketing attribution.
- Use team_id for round-robin or territory-based assignment. Define assignment rules in crm.team.
- When building API integrations, use the XML-RPC or JSON-RPC API. The crm.lead model is fully exposed. Map external CRM IDs to a custom field like ref for sync.
- For custom fields, use the
x_prefix or a module prefix to avoid conflicts with future Odoo versions.
Common Mistakes
- Creating duplicate leads instead of searching by email_from. Use
email_normalizedor a deduplication check before creating. - Mixing up type (Lead vs Opportunity) and stage_id. Type determines the record type. Stage determines position in the funnel. Both matter for reporting.
- Forgetting to set user_id or team_id. Unassigned leads get lost. Configure automatic assignment or ensure manual assignment.
- Overriding conversion logic without calling super(). The action_convert method does important work. Extend it, do not replace it blindly.
- Adding required custom fields without defaults. Existing leads will fail validation when you upgrade the module.
Conclusion
The crm.lead model is central to Odoo CRM. It stores leads and opportunities and drives the sales pipeline. Understanding its fields and how modules extend it will help you configure, customize, and integrate Odoo effectively.
Whether you are a functional consultant mapping sales processes or a developer building custom CRM modules, a solid grasp of crm.lead will save time and prevent errors.
Need Help With Your Odoo Implementation ?
Dasolo helps companies implement, customize, and optimize Odoo. We specialize in API integrations and Odoo development. Our team has deep experience with the Odoo data architecture and models like crm.lead.
If you need help with your Odoo implementation, custom CRM modules, or integrations, we are here to help. Book a demo to discuss your project.