Building custom entities in EspoCRM when standard records do not fit
A team tracks equipment leases, software licenses or delivery projects in spreadsheets because none of EspoCRM's standard records fit them. Leads, accounts, contacts and opportunities describe customers and sales activity well, but they were not designed to hold a serial number, a renewal date or a set of contract terms. Before anyone opens the Entity Manager, decide whether the thing being tracked has its own lifecycle, its own owner and its own list view. If it does, a custom entity is usually the right answer. The Entity Manager lets administrators create entity types, add custom fields to them and define relationship types that link the new records to accounts, contacts and opportunities. Choose the entity type template with care: Base is a plain record with no built-in person or company fields, Person suits individuals who need name and contact fields, and Company suits organizations. Confirm the exact field sets for each template in the version you deploy, since they determine what you inherit.
A custom field is enough when the information describes an existing record and never needs its own list, permissions or history. A contract value on an opportunity, or a renewal flag on an account, usually belongs in a field. A new entity is worth the added maintenance when several records of the new type can attach to one parent, when different teams need different access to them, or when reports must count them separately. Relationship types need the same care: decide whether a link is one-to-many or many-to-many before you create it, because changing it later affects existing data. Map each new entity to the teams that will use it and the layouts they will see, and record the decisions in a short data model document. Automated steps around these records, such as approvals or renewal reminders, rely on the Advanced Pack's Workflows and Business Process Management, so confirm early whether that official add-on is part of your plan.
Entity types, field types and relationship types compared
This table compares the entity types, field types and link types a designer chooses between in the Entity Manager, with when each fits and what it costs to change later. Check the exact options in your EspoCRM version, since the current release line is 10.0.x, and treat any change to a type that already holds records as a data migration.
| Option | When it fits | Cost to change later |
|---|---|---|
| Base entity type | Records with no natural person or organization identity, such as projects, contracts or orders. Designers add their own fields and links. | Low while the entity is empty. Once records exist, changing its type or structure needs a data migration plan. |
| Person entity type | Individuals such as contacts or leads, when the standard person fields for name, email and phone match the process. | Low if the standard fields are kept. Repurposing them later affects existing data, layouts and any formulas that read them. |
| Company entity type | Organizations such as customers, partners or suppliers that other records link to. | Moderate. Existing links, duplicate rules and imports depend on the entity, so confirm the impact before switching the design. |
| Text, varchar, integer and float fields | Reference codes, notes, quantities and measured values that formulas, reports or filters will read. | Low when added early. Changing the field type later needs data conversion, and some values may not convert cleanly. |
| Enum and multi-enum fields | Fixed option lists such as pipeline stages, product categories or service tiers. | Adding options is simple. Renaming or removing options leaves existing records with old values, which need cleanup in formulas, dynamic logic and reports. |
| Date, datetime and currency fields | Deadlines, renewal dates and amounts that reports, formulas and PDF templates calculate on. | Moderate. Changing date or currency handling after data exists affects calculations and reports, so test with real sample records first. |
| One-to-many link | One parent record owns many children, such as an account with many opportunities. | Low to add. Converting to a many-to-many link later means reworking the link structure and checking existing associations. |
| Many-to-one link | Many child records point to one parent, such as many orders for one customer, with the link stored on the child. | Low to add. Reversing the direction later usually needs new fields and reconnecting existing records. |
| Many-to-many link | Records that share many others, such as one contact working on several projects, where either side needs a list of links. | Most flexible for linking, but labels, layouts and imports need planning. Changing it later is a data migration, so confirm the relationship types offered in your version first. |
Creating custom entities in the Entity Manager, step by step
This sequence takes a business object from a named owner and a clear purpose to a working entity with fields, linked records, layouts and permissions that teams have tested under their own roles. Each step ends with a check so problems surface before the entity reaches daily use.
Confirm the business object and its owner
Before opening the Entity Manager, the business owner and the platform lead agree on what the object represents, such as a contract, an installation or a grant application, and which team owns its data. Write down the questions the object must answer, the existing records it relates to and who will create and edit it. The step is done when the owner signs off on a one-page definition that lists the purpose, the owning team and the records it links to. This definition drives every later choice, including the entity type and the access model.
Create the entity with the correct type
In Administration, open the Entity Manager, choose to create an entity, and give it a name that follows your naming conventions. Select the entity type that matches the object: Base for records that stand on their own, Person or Company where the record represents someone or an organization and needs the fields those types provide, or another type where the documentation fits. Check the type against the definition from the previous step before saving. The step is done when the new entity appears in the Entity Manager list and opens without errors in a test record.
Add custom fields with the right types
Add each field the definition requires in the Entity Manager, choosing a field type that matches the data: text, enum, date, currency, link or another type offered by the form. Mark required fields only where the business process needs them, and set options for enum fields from the agreed vocabulary. Custom fields receive the c prefix, so confirm the generated names are consistent with your naming standard before records depend on them. The check is that each field appears on a new test record in the edit view with the expected type and validation.
Define relationships to existing entities
Create the links between the new entity and existing entities, such as Account, Contact or Opportunity, choosing the relationship type that reflects the real cardinality, one to many or many to many. Name each link so that it reads clearly from both sides. The check is to open a related record on each side and confirm the relationship appears in both directions, with the correct link panel and the expected records listed. If a link is missing from one side, correct it before adding layouts, because layouts depend on these links.
Set layouts and access for each team
Configure the detail, list and edit layouts for the entity, placing the fields that each team needs and hiding those they do not. Then set the roles that govern who can read, create, edit and delete records, and assign teams where ownership matters. Confirm the permissions with the owner before testing, since role changes affect what users see from the first login. The step is done when the layouts match the definition and the role matrix is written down for the test plan.
Test with sample records as each role
Create sample records as illustrative test data, then sign in or impersonate users with each role in the matrix. Check that each role can see, create, edit and delete only what it should, that required fields behave as designed and that related records appear on both sides. Record any failures against the step where they originated, fix them and retest. The step is done when every role passes the test script and the owner accepts the results. Ask your implementation partner or internal team to confirm how test accounts are created and removed in your environment.
Choosing custom entities by team or data situation
Sales teams often need to track a product, subscription or contract that sits alongside an opportunity. When one opportunity can carry several line items with their own dates, quantities and statuses, a custom entity fits better than adding more fields to the Opportunity. The relationship usually runs one-to-many from Opportunity to the contract or line item records. If one contract can cover several opportunities, a many-to-many relationship is needed, and that choice affects reporting and how commissions are calculated.
- Entity type: Use a custom entity for line items or contracts that have their own lifecycle. Keep simple attributes, such as a single discount reason, as fields on an existing entity.
- Relationship pattern: Link line items to the Opportunity with one-to-many, and add many-to-many only when one contract truly spans several opportunities.
- Ownership of pricing data: Agree who maintains the product catalog and price fields, usually sales operations or finance, and who can edit them on a live record.
- Renewal and status fields: Confirm who owns renewal dates and status changes, since these drive reminders, dashboards and any workflow that follows.
- Reporting needs: Ask finance and the sales leader which totals and currency views they need before naming fields, so the structure supports those reports from day one.
Before sign-off, confirm with the business owner which fields feed revenue reporting, because changing a relationship after records exist is far more costly than settling it during design.
Service teams usually track physical or licensed assets, such as equipment at a customer site, and tie them to cases and the account that owns them. The asset is a record in its own right, with serial numbers, location, warranty dates and service history. Cases then link to the asset they concern and to the account, so a team can see every open issue on a device. The main design question is whether an asset belongs to the account, to a contact or to a site, because that decides who sees it and what happens when the customer changes.
- Entity type: Model assets as a custom entity when they have independent history, warranties or maintenance cycles. Keep one-off notes on the case itself.
- Relationship pattern: Use one-to-many from Account to Asset, and link each Case to both the Asset and the Account so reporting works at either level.
- Ownership on transfer: Decide how an asset moves when a customer is acquired or leaves, and whether its case history stays with the old account.
- Warranty and entitlement data: Confirm the source of warranty dates and who updates them, whether that is the manufacturer feed, the contract team or service staff.
- Retention and closure rules: Agree how long asset and case records are kept after service ends, and who may close or reopen cases.
Before sign-off, ask the service owner to walk through three real service scenarios, including a resale and a multi-site customer, to confirm the links hold up under those cases.
Some teams need customers to view or update their own records, such as orders, service requests or project status, through a portal. The entity design has to serve two audiences at once: internal staff who need full data and customers who should see only a subset. A portal user typically reaches records through a relationship to their account, so the links you build determine what they can see. Field and entity visibility for portal roles must be planned alongside the data model, not added later as an afterthought.
- Entity type: Use a custom entity for customer-facing items, such as a service request, and keep internal-only fields on a separate internal entity or record type.
- Relationship pattern: Link portal records to the customer's Account or Contact, and confirm that a user linked to one account cannot reach another account's records through chained relationships.
- Visible fields: Ask the business owner which fields customers may see or edit, and exclude internal pricing, margins and notes from portal views.
- Access approval: Decide who approves portal access for each customer and how access is removed when a contact leaves the customer organization.
- Data minimization: Limit what is stored in customer-facing records to what the portal needs, which reduces exposure if access is misconfigured.
Before sign-off, have the business owner test the portal as a customer user with each relationship path, and confirm the portal role settings against the security documentation for the version you run.
Where custom entities end and workflows, hooks or extensions begin
The entity and its fields hold the data model: what a record is, which attributes it carries and how it links to other records. Behavior is a separate layer. Formula scripts, workflows, server-side hooks and packaged extensions add behavior, and each one should be justified by a rule that must run at a specific moment. Before adding any of them, confirm that the data model answers the business question on its own. A custom Project entity with a status enum, a link to Account and a few date fields often needs no code at all, and every script or hook you add becomes something a later upgrade or a new administrator has to understand.
Formula Script is EspoCRM's built-in scripting language. According to the EspoCRM formula documentation, it runs in before-save scripts configured in the Entity Manager, in API before-save scripts, and in workflows and BPM. Use it for calculated values and validation that must hold whenever a record is saved, such as deriving a total from line items or rejecting an impossible date range. Workflows and BPM are not part of the core product: according to the EspoCRM Advanced Pack page, they come from the Advanced Pack, which is included in all EspoCRM Cloud plans. Confirm with your vendor or partner whether a self-hosted edition requires the Advanced Pack license before you design approval or assignment flows around it.
Keep the model simple first, then check each proposed behavior against three questions: does it run on save or on a schedule, does it need to read or write other entities in a way the Entity Manager cannot express, and will it survive an upgrade. Formula scripts cover most save-time rules. Hooks, which are PHP code, are for logic that Formula cannot reach and should be documented as custom code from the start. Packaged extensions are the right home for anything you plan to reuse across instances. Record the decision for each rule in your design document so that the people who maintain the instance can tell which behavior lives in the model and which lives in code.
Access, API and data risks in custom entity models
A new entity type is only as safe as the roles, API access, data retention and admin practices around it. The cards below cover the places where a custom model most often exposes data beyond the team that needs it, and the checks to run before go-live.
Over-broad role permissions on new entities
A new entity has no access rules until someone sets them, and a role copied from an existing one often grants read or export rights across all records. Review each role for the new entity's scope (all, team, own or none) and for actions such as export, mass update and delete. Test the result by logging in as a representative user from each team and confirming they cannot see records outside their scope. Under the default scope set to all, a single missed setting can expose the whole table.
API exposure through API users
Every entity with API access enabled becomes reachable through the REST API, and API users carry their own role permissions that may be broader than a UI user's. Confirm which API users exist, which authentication method each uses, and which entities their roles allow them to read or write. The API documentation describes HMAC as the most secure method and basic authentication as not recommended, so check the method before issuing credentials.
Personal data without a retention plan
Custom fields for national IDs, dates of birth, health notes or income ranges are easy to add in the Entity Manager and hard to find later. Each personal data field needs a named owner, a documented purpose and a deletion or anonymization rule. Ask who can export these fields through CSV or PDF output, because export paths often bypass the screens that hide them. Retention rules are an organizational decision, so agree them before the first record is created.
Relationships that cross team boundaries
A relationship between two entities can make records visible to users who only have access to one side of it. For example, a link from a cross-team project to a client account may let a team member open account details they were never meant to see. Map each relationship to the teams that should see both sides, and test related-record panels, not just the entity's own list view. Where a relationship is only needed for reporting, consider whether a field or an agreed report is enough.
Admin accounts used for model changes
Entity Manager changes, layout edits and role updates all run under administrator rights, so a daily-use admin account turns a phishing or session theft incident into a model-wide change. The security docs recommend avoiding admin accounts for daily work, so create a separate admin account used only for configuration and keep its session short. Pair it with 2FA and restrict access to the admin area by IP address where your network allows it.
Unreviewed model changes in production
Entity and field changes made directly on a live instance are hard to reproduce, audit or roll back. Record each change in a ticket, test it on a copy of the instance, and keep a dated export of the metadata before and after the change. Ask your implementation partner how the change log will be kept and who approves production changes. Keep an eye on the instance's version too, since upgrades change how some metadata is handled.
What custom entities cost to design and build in EspoCRM
What drives the cost of building custom entities in EspoCRM?
The main drivers are the number of entities, the number and complexity of relationships between them, the roles and portal access you need, the volume and quality of data to migrate, and the testing required before go-live. Each entity adds layouts, fields, permissions and search views to design and check, and each relationship adds a link that has to behave correctly from both sides. A small set of entities with clear ownership rules is far quicker to scope than a model where many objects share teams, portals and reporting. Ask for each of these drivers to be listed separately in the written scope so you can see which parts move the price.
Is EspoCRM itself a recurring cost?
It depends on how you deploy it. The open-source edition is licensed under AGPL-3.0 and can be downloaded and self-hosted for free, according to the EspoCRM pricing page. Your recurring costs then sit in the infrastructure you run, the time your team spends on upgrades and backups, and any services you buy. If you choose EspoCRM Cloud instead, the pricing page lists 15 US dollars per user per month on the Basic plan (minimum 3 users), 25 dollars on Enterprise (minimum 5 users) and 69 dollars on Ultimate (minimum 10 users), with the Advanced Pack included in all cloud plans. Confirm current prices on that page before budgeting.
Can our internal administrator build custom entities without a partner?
Often yes for a small, well-defined model. The Entity Manager, layouts and field types are accessible to an administrator who understands your processes and can test changes in a non-production instance. Work usually becomes harder when entities need custom PHP hooks, formula logic across records, portal access, SSO group mapping or a migration from a spreadsheet or another CRM. Consider whether your administrator has time to design, test and document the model, and whether someone can review changes before they reach production. A partner is most useful as a second pair of eyes on the design and as a delivery team for the parts you do not want to own.
How long does a data model review take?
The length depends on scope, mainly the number of entities, the relationships between them and how many teams, roles and portals must see different parts of the model. A review of a short list of entities with clear owners is a much smaller exercise than a model that spans sales, service and partner access. Your team can shorten the review by bringing a list of entities, the fields each team needs, the relationships users describe in plain language and the reports that must work at the end. Any timeline should come from the written scope, not from a general estimate.
What should we send to get a quote for custom entities?
Send a short brief that describes the business process, not only the screens. Include the entities you think you need, the relationships between them, which teams create, edit and view each record, whether portal users need access, and where existing data lives with its approximate record counts and quality issues. Also list the integrations involved, such as identity provider, email or accounting systems, the EspoCRM version and hosting model you plan to use, and the reports or dashboards that depend on the model. Ask the provider to list assumptions, exclusions and the testing they will perform.
What costs are one-time and what recurs after go-live?
One-time costs usually include the model design, entity and layout build, data migration, testing, documentation and training. Recurring costs include hosting, backups, patching, licenses if you use a paid tier, and the time to maintain new fields and relationships as the business changes. Ask the provider to separate these in the quote and to state which items are fixed for the agreed scope and which would be billed as changes. Ongoing support and upgrades can also be arranged as a retainer, which gives a predictable recurring line.
How do roles and portal access change the cost of a custom entity?
Each role that sees or edits an entity needs its own permission set, and each team may need its own layout. Portal access adds another audience with different visibility rules, which must be tested separately from internal users. A model with several roles and portal users needs more design time, more test cases and more verification that users cannot reach records outside their scope. Ask the provider how they will test access for each role, including a negative test for records a user should not see, and whether that testing is included in the fixed scope.
What to confirm in your version and environment before you build
Entity and relationship work in EspoCRM depends on the exact release, the server stack and the way automation and API access will be wired. The cards below list the checks to complete with your team before you create the first custom entity.
Entity and relationship types offered
Confirm which entity types (Base, Person, Company, Event and others) and which relationship types your EspoCRM version exposes in the Entity Manager. Options can differ between releases, so check them against the version you will deploy, not the one in older guides. Record the exact list in your design document so the build team and reviewers work from the same baseline.
Custom prefix and upgrade impact
Confirm how the c prefix is applied to custom entities and fields in your version, and whether custom names collide with core or extension names. Ask whether the prefix changes how extensions, formula scripts and API routes reference your objects. Decide now which custom code will depend on those names, because renaming an entity after data exists is expensive.
PHP and database requirements
Check the PHP range, database engine and version, and web server listed in the server configuration docs against your hosting platform. Confirm that your MySQL, MariaDB or PostgreSQL version meets the minimum before you test schema changes, because rebuilds and custom field additions run database operations that a mismatched stack can fail. Include the scheduled task for background jobs in the same check.
Advanced Pack need for automation
Decide whether the entities you design will drive workflows or BPM processes. Those features come from the Advanced Pack, which is included in all EspoCRM Cloud plans, so self-hosted editions must confirm licensing for it separately. If your automation only needs field-level formula logic or hooks, confirm that the base edition covers it before you commit the design to paid extensions.
API user access to new entities
Map which API users will read or write the new entities and which authentication method each will use. The REST API supports API key, HMAC and basic authentication, and the docs describe HMAC as the most secure and basic authentication as not recommended. Confirm that each API user role grants read and write access to the new entity and its relationships, and test those permissions before integrations go live.
Upgrade path to the 10.0.x line
Confirm how your current instance will move to a newer release such as the 10.0.x line, and whether your custom entities, layouts and formulas need retesting after the move. Note that upgrading through the UI is disabled by default as of version 10.0, so plan the command-line process and a tested backup first. Ask who will own the upgrade test cycle after go-live.
How DeployOpen scopes and delivers custom entity models
DeployOpen plans, builds, documents and supports custom entities and relationships in EspoCRM inside your own infrastructure. We start from how your teams sell and serve customers, then turn that model into Entity Manager configuration that your administrators can read, change and maintain after handover.
How we scope
- Map the business objects your teams track and the relationships between them before any entity is created.
- Agree in writing which entity types, custom fields, relationship types and layouts are in scope.
- Name the users, teams and portal roles that will need access to each new entity from day one.
- Engagements are fixed-scope, so deliverables and timelines are confirmed in writing before work starts.
How we build
- Create custom entities with the Entity Manager, using the c prefix convention for custom fields and entities.
- Choose the Base, Person or Company type for each entity based on how records must behave.
- Configure one-to-many, many-to-many and parent relationships, checking the link names on both sides.
- Test record creation, linking, search and permissions with sample data in a non-production instance first.
How we hand over
- Document each entity, field and relationship with its purpose, owner and the roles that can edit it.
- Record which changes were made through the Entity Manager so administrators can repeat them safely.
- Run a walkthrough with your administrators on adding fields and relationships without breaking existing data.
- Keep custom definitions separate from future extension code so later upgrades remain manageable.
How we support
- Review the entity model when new products, teams or regulatory requirements change the data you hold.
- Plan entity and relationship changes ahead of each EspoCRM version upgrade, including checks on custom fields.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Confirm with your team which support hours and response expectations apply before the retainer starts.
