Entities & roles
An entity is the shared identity record for a person, organisation, or group in Efimis. It stores who a party is and how to contact them. Separate role records describe how that party participates in the firm’s work.
This separation matters when integrating with Efimis. An entity can exist without being a client, employee, or supplier, and the same entity can hold more than one of those roles.
Entity types
Section titled “Entity types”Efimis supports four entity types:
| Type | Use |
|---|---|
| Individual | A natural person. Uses fields such as first name, middle names, last name, title, and initials. |
| Organisation | A company, government body, trust, partnership, or other named organisation. |
| Group | A collection or joint party that needs a shared identity in addition to its members. |
| Unspecified | A transitional value for records whose type has not yet been resolved. Avoid creating new records with this type when the correct type is known. |
Individuals normally require a first and last name. Organisations and groups use an organisation name and can also carry registration numbers and an organisation type. All entity types can have a preferred name, email address, phone numbers, addresses, and a preferred contact channel.
Entities and roles
Section titled “Entities and roles”Role records extend an entity with information needed for a particular business function:
| Role | Purpose | Identifier |
|---|---|---|
| Client | A party for whom the firm acts and against whom matters can be opened. | client_… |
| Employee | A member of the firm who can participate in matters and record work. | employee_… |
| Supplier | A party from whom the firm buys goods or services. | supplier_… |
The role ID and entity ID are different identifiers. For example, a matter’s clientId refers to the client role, while clientEntityId refers to the underlying entity.
See Resource identifiers for the ID format and guidance on storing and using Efimis resource IDs.
Role records also have their own state and business data. Closing a client or supplier does not erase the shared entity, and updating an entity’s address does not change the financial state of its roles.
Contact and identity information
Section titled “Contact and identity information”An entity brings the information used to identify and contact a party into one place:
- names and preferred display name;
- organisation and registration details;
- email and preferred contact channel;
- typed phone and fax numbers;
- street, postal, and billing addresses;
- primary contact, where another entity is the contact for an organisation; and
- created and updated audit information.
Efimis derives convenient display fields such as fullName, sortName, and formatted address values. Treat those as read models: integrations should update the underlying name and address fields rather than attempting to maintain the derived values.
Relationships between entities
Section titled “Relationships between entities”Entities can be connected by named, directed relationships. A relationship identifies a target entity, describes the target’s role relative to the source entity, and can include a memo. Examples include a person belonging to a joint party or an organisation having a nominated contact.
Relationships are separate from client, employee, and supplier roles. They describe how two parties relate; roles describe how an entity participates in the Efimis platform.
When an upstream system represents several people on one card, an integration may create a parent group and an individual entity for each person, then link the individuals to the group. Preserve the distinct entity IDs so each person can later be searched, contacted, or assigned another role independently.
Entity lifecycle
Section titled “Entity lifecycle”Entities move through these states:
- Draft — creation is incomplete and some operations may be restricted.
- Active — the entity supports normal operations.
- Deleting — deletion has been requested but dependent records still need to be resolved.
- Deleted — the entity is no longer active in ordinary workflows.
An entity with active client, employee, or supplier roles may not be immediately deletable. Close or remove dependent roles through their own lifecycle before assuming the underlying entity can be deleted. Use the undelete operation when a deleted entity needs to be restored; creating a duplicate loses its established identifiers and relationships.
Ownership in integrated environments
Section titled “Ownership in integrated environments”Some tenants receive entities from another practice-management or case-management system. In that arrangement, the upstream system may remain the source of truth for names and contact information. Changes made directly in Efimis may be disabled or overwritten by the next synchronisation.
Integrations should establish ownership per field, keep the upstream identifier alongside the Efimis entity ID, and update records rather than recreating them.
In the REST API
Section titled “In the REST API”The entity endpoints support searching, creating, reading, patching, deleting, activating, restoring, and managing entity relationships. Client, employee, and supplier endpoints manage the role-specific records.
See the REST API reference for the current request and response schemas, and continue with Matters & clients to see how client and employee roles participate in legal work.