Entity Types

Entity types are the building blocks of your data schema in SignalSmith. They represent the core business objects in your domain — Users, Accounts, Products, Orders, and any other concept central to your business.

What Is an Entity Type?

An entity type is a named category of business object with a defined set of attributes. Think of it as a “table definition” for your semantic data model, but decoupled from any specific warehouse table. Multiple models can contribute data to the same entity type, and a single entity type can be used across syncs, audiences, identity resolution, and journeys.

Built-In Entity Types

SignalSmith provides two default entity types that cover the most common CDP use cases:

User

The primary entity representing individual people — customers, contacts, leads, or end users.

Default attributes:

• id — Internal unique identifier
• email — Email address
• phone — Phone number
• first_name — First/given name
• last_name — Last/family name
• created_at — When the user was first seen

Account

Represents organizations, companies, households, or any grouping of users.

Default attributes:

• id — Internal unique identifier
• name — Account/organization name
• domain — Company domain (e.g., example.com)
• industry — Industry classification
• created_at — When the account was first seen

You can modify these defaults, add attributes, or delete them entirely if they don’t fit your use case.

Creating an Entity Type

Using the UI

1. Navigate to Schema in the left sidebar
2. Click Add Entity Type
3. Enter a name for the entity type (e.g., “Product”, “Subscription”, “Event”)
4. Optionally add a description explaining what this entity represents
5. Define the attributes for the entity type (see below)
6. Click Save

Using the API

curl -X POST https://your-workspace.signalsmith.dev/api/v1/entity-types \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product",
    "description": "Products in the catalog available for purchase",
    "attributes": [
      {
        "name": "product_id",
        "type": "string",
        "is_identifier": true,
        "is_primary_key": true
      },
      {
        "name": "sku",
        "type": "string",
        "is_identifier": true
      },
      {
        "name": "name",
        "type": "string"
      },
      {
        "name": "category",
        "type": "string"
      },
      {
        "name": "price",
        "type": "number"
      },
      {
        "name": "in_stock",
        "type": "boolean"
      }
    ]
  }'

Defining Attributes

Each entity type has a list of attributes that describe its properties. Attributes have the following configuration:

Attribute Properties

Attribute Types

Identifier Attributes

Marking an attribute as an identifier means it can be used to match records across data sources. Common identifier attributes:

• email — Match by email address
• phone — Match by phone number
• external_id — Match by a system-specific ID
• domain — Match accounts by company domain

Identifier attributes are particularly important for Identity Resolution, where they’re used to merge profiles from different data sources.

Primary Key

Every entity type must have exactly one primary key attribute. The primary key uniquely identifies each instance of the entity type. For example:

• User entity: user_id or email
• Account entity: account_id or domain
• Product entity: product_id or sku

Mapping Attributes to Models

After defining an entity type, you connect it to your data by mapping its attributes to columns from one or more Models.

Single-Model Mapping

The simplest case — one model provides all the data for an entity type:

Model: "All Customers"              Entity Type: User
┌─────────────────────┐             ┌─────────────────┐
│ customer_id   ──────────────────▶ │ id (PK)         │
│ email_address ──────────────────▶ │ email           │
│ phone_number  ──────────────────▶ │ phone           │
│ fname         ──────────────────▶ │ first_name      │
│ lname         ──────────────────▶ │ last_name       │
│ created       ──────────────────▶ │ created_at      │
└─────────────────────┘             └─────────────────┘

Notice that column names in the model don’t need to match attribute names — you map them explicitly.

Multi-Model Mapping

For complex data models, multiple models can contribute to the same entity type. Each model maps to an access filter of attributes, and SignalSmith merges them using the primary key:

Model: "CRM Contacts"              Entity Type: User
┌─────────────────────┐             ┌─────────────────┐
│ contact_id   ──────────────────▶ │ id (PK)         │
│ email        ──────────────────▶ │ email           │
│ name         ──────────────────▶ │ first_name      │
└─────────────────────┘             │                 │
                                    │                 │
Model: "Product Analytics"          │                 │
┌─────────────────────┐             │                 │
│ user_id      ──────────────────▶ │ id (PK)         │
│ ltv          ──────────────────▶ │ lifetime_value  │
│ last_active  ──────────────────▶ │ last_seen       │
└─────────────────────┘             └─────────────────┘

Both models map to the id primary key, which SignalSmith uses to merge the data.

Managing Entity Types

Editing an Entity Type

1. Navigate to Schema in the sidebar
2. Click on the entity type to edit
3. Add, remove, or modify attributes
4. Click Save

Considerations when editing:

• Adding new attributes does not affect existing syncs or audiences
• Removing attributes may break syncs or audiences that reference them
• Renaming an attribute is treated as removing the old one and adding a new one — remap downstream resources

Deleting an Entity Type

1. Navigate to Schema in the sidebar
2. Click on the entity type to delete
3. Click Delete
4. Confirm the deletion

SignalSmith prevents deletion if the entity type is used in:

• Active relationships
• Audience definitions
• Identity resolution rules
• Journey triggers

Remove these dependencies first.

Example Entity Types

E-Commerce

SaaS B2B

Media / Content

Next Steps

• Define relationships between your entity types
• Visualize your schema with the ERD viewer
• Set up identity resolution using entity identifiers