Entity
An entity in Salesforce is the general term for any data structure the platform can address as a holder of records or metadata.
Definition
An entity in Salesforce is the general term for any data structure the platform can address as a holder of records or metadata. That set includes standard objects (Account, Contact, Case), custom objects (MyObject__c), external objects (Acme__x), big objects (Audit__b), platform events (Order_Status__e), and custom metadata types (My_Setting__mdt). The word comes from database modeling, where an entity is the abstract thing and a table is the concrete implementation. Salesforce keeps the term for its metadata layer.
Most people say object in everyday work, and Setup uses that word in the UI. Entity is the broader, lower-level vocabulary the platform uses in the Tooling API, in metadata responses, and in error messages such as FIELD_NOT_FOUND on entity Account. Knowing both words lets you translate between what you click in Setup and what the API reports back. The Tooling API exposes entities through the EntityDefinition object and their fields through EntityParticle.
How entities show up across the platform
Entity versus object: the abstract and the concrete
Object is the word you see in Setup and in most documentation. Account, Contact, and MyObject__c are objects. Entity is the platform vocabulary for the same idea, pulled up one level of abstraction so it can cover everything addressable. Every object is an entity, but entity also stretches to include things that are not objects in the everyday sense, such as platform events and custom metadata types. The split exists because Salesforce borrowed entity from relational database modeling, where an entity is the concept (a Customer) and a table is the physical structure that stores it. When you read API guides, the rule of thumb is simple. The user-facing surface says object. The metadata and tooling surface says entity. They point at the same constructs in nearly every case. The one place this matters in practice is reading documentation and error text. A guide that mentions EntityDefinition is talking about object metadata. An error that names an entity is naming an object. Translating between the two words removes most of the confusion that the term causes for people new to the API.
The EntityDefinition object in the Tooling API
EntityDefinition is a Tooling API object that gives row-based access to metadata about standard and custom objects. Instead of describing schema in XML, you query it with SOQL and get one row per entity. A query like SELECT DurableId, QualifiedApiName, Label, DeveloperName, KeyPrefix, IsCustomizable FROM EntityDefinition returns the org schema as data you can sort, filter, and join. The fields tell you what each entity is. QualifiedApiName is the API name you use in code, such as Account or MyObject__c. KeyPrefix is the three-character prefix that starts every record Id for that entity. IsCustomizable flags whether you can add fields and customize it. DurableId is a stable identifier that survives renames, which makes it the safe key to store in tooling. Because the result is a queryable list, EntityDefinition is the backbone for schema documentation generators, governance scanners, and admin utilities that need to walk an org without hard-coding object names. It answers the question what objects exist here in a single call.
EntityParticle for the fields inside an entity
Where EntityDefinition describes the entity itself, EntityParticle describes the parts inside it, mainly the fields. It is the field-level companion in the Tooling API. A query such as SELECT QualifiedApiName, Label, DataType, Length, IsCreatable FROM EntityParticle WHERE EntityDefinitionId = the-account-id returns one row per field on that entity. The metadata is rich. DataType tells you whether a field is text, a picklist, a lookup, or a number. Length gives the size for text fields. Flags such as IsCreatable and IsUpdatable describe what the API will let you do. Pairing EntityDefinition with EntityParticle lets you walk an entire schema programmatically: list every entity, then for each one list every field with its type and rules. That pattern powers data dictionaries, migration planning tools, and field-usage audits. It works without compiling Apex, so external tools and scripts can read schema over the REST-based Tooling API and build a full picture of the data model on demand.
The entity types and their API suffixes
Salesforce uses a small set of suffixes to mark what kind of entity an object is, and the suffix tells you how it behaves. Standard objects like Account and Contact have no suffix and ship with the platform. Custom objects end in __c and store records you define. External objects end in __x and map to data living in an outside system, fetched on demand rather than stored in Salesforce. Big objects end in __b and hold very large volumes of archive-style data with a query model built for scale. Platform events end in __e and act as publish-subscribe message channels rather than stored tables. Custom metadata types end in __mdt and store configuration that deploys between orgs. All of these surface in EntityDefinition, each with its own KeyPrefix and its own CRUD and query rules. The suffix is the fastest way to read an entity at a glance. When you see Acme__x in a query or an error, you know it is an external object before you check anything else, and you know its data does not live inside your org.
Platform events and custom metadata as entities
Two entity types confuse people because they look like objects but do not behave like ordinary tables. Platform events carry an API name ending in __e, have fields, and let you call insert in Apex. The catch is that inserting a platform event does not store a row. It publishes a message that subscribers receive, then the event is gone. So the entity exists in the metadata layer and supports a CRUD-shaped API, but there is nothing to query afterward in the normal sense. Custom metadata types end in __mdt and store rows that behave like configuration rather than transactional data. Their records deploy with your metadata, so the same values move from sandbox to production through a change set or package. That is why they suit feature switches, mapping tables, and tier rules. Both types appear in EntityDefinition alongside ordinary objects, which is the clearest sign that entity is a wider category than object. Treating them as plain tables leads to surprises, so it helps to remember what each one actually does.
Reading entities in error messages
The platform leans on the word entity in its error text, and learning the pattern speeds up debugging. A message like FIELD_NOT_FOUND on entity Account almost always means a field name in your code or query does not match the API name on that object, often a typo or a missing __c suffix. INVALID_FIELD on an entity frequently points at field-level security, where the running user cannot see a field that does exist. INVALID_TYPE on entity X usually means the object name itself is wrong or the user lacks access to the object. The vocabulary here predates the modern Setup UI, which is why the runtime says entity while the UI says object. They name the same thing. When an integration or an Apex test throws one of these, the fix is to map the entity name in the error to the object in Setup, then check the field names, the field-level security, and the object permissions in that order. The error wording stays consistent across the SOAP, REST, and Bulk APIs, so it is worth memorizing.
Entity Definition relationships on custom metadata types
One place entity appears directly in the point-and-click UI is custom metadata types. When you add a field to a custom metadata type, one field type is the Metadata Relationship, and one target you can pick is Entity Definition, described in Setup as the metadata of a standard or custom object. This lets a configuration record point at an object by reference rather than by a hard-coded text name. A common use is storing rules that apply per object. You might build a custom metadata type that holds service-level targets, with an Entity Definition field that names which object each rule covers. Because the relationship resolves through metadata, it survives object renames better than a plain text field would, and Apex can read the related object cleanly. There is also a Field Definition relationship that points at a single field through EntityParticle, for rules that need to target one column. These relationships, added in the Spring 17 release, turn the entity layer into something admins can reference without writing code, which is useful for building reusable, object-aware configuration.
How to reference an entity from a custom metadata type
You do not create an entity on its own, since standard and custom objects are the entities. But you can reference one through an Entity Definition relationship on a custom metadata type, which lets a configuration record point at an object by metadata rather than by a typed-in name. Here is how to add that field in Setup.
- Open the custom metadata type
In Setup, go to Custom Metadata Types, then click Manage Records, or open the type definition. You add the relationship on the type, the same place you add any custom field to it.
- Add a Metadata Relationship field
Under Custom Fields, click New. Choose the Metadata Relationship field type. This is the only field type that can point at object or field metadata rather than storing plain data.
- Select Entity Definition as the target
When asked what the relationship points to, choose Entity Definition, described as the metadata of a standard or custom object. To target a single field instead, choose Field Definition, which resolves through EntityParticle.
- Name the field and save
Give the field a clear label and API name, set who can see it, then save. Each record of the type can now select which object it applies to from a metadata-backed lookup.
Points a custom metadata record at a standard or custom object. Resolves through EntityDefinition, so it survives renames better than a text field.
Points at one field on an object. Resolves through EntityParticle, for rules that must target a single column rather than a whole object.
A public custom metadata type cannot relate to a protected one. Decide visibility before wiring relationships, because it constrains what you can reference.
- You cannot create an entity from this screen. The relationship only references objects that already exist in the org.
- A public custom metadata type cannot be related to a protected custom metadata type, so plan visibility first.
- Read the related object in Apex through the relationship field, not by parsing a stored name string, so renames do not break your logic.
Prefer this walkthrough as its own page? How to Entity in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Entity.
Hands-on resources to go deeper on Entity.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Which Tooling API object exposes metadata about every customizable Entity in an org, including standard objects, custom objects, and platform events?
Q2. The term Entity covers a slightly broader set than the everyday term Object. Which of these is an Entity that is not a conventional database object?
Q3. Where in the Salesforce platform does the word Entity most often appear instead of Object?
Discussion
Loading discussion…