Skip to main content

Entities

Esper encodes traffic automatically, but the tenant still needs to define what counts as an entity for their property.

If you are unsure which fields you can use, open the Field Reference. It explains the field list shown in the builder in non-technical language.

Examples:

  • Example: source_id + request_header_user_agent
  • Example: cookie + path pattern
  • Example: ip + referer + action

What an entity definition contains​

Each entity definition includes:

  • entity_definition_id: The unique identifier for the entity definition.
  • tenant_id: The tenant that owns the entity definition.
  • name: The business-friendly name for this identity rule.
  • description: A short explanation of what this entity represents.
  • enabled: Whether Esper should use this entity definition.
  • priority: The evaluation order when multiple entity definitions could match.
  • key_fields: The fields Esper combines to create the entity key.
  • match_expression: The optional condition that limits when this entity applies.

Why this matters​

Entity definitions tell Esper how to:

  • Group related traffic.
  • Accumulate state.
  • Analyze repeated behavior.
  • Bind policies to the right identity semantics.

Choosing key fields​

Key fields tell Esper which values should stay stable when two requests belong to the same real-world actor, device, session, or account.

In the builder, you are usually choosing from the tenant's available field catalog directly. For match expressions, you may also use request-oriented conditions such as method, header, query parameter, cookie, or body data reference.

Examples of strong key fields:

  • Account or customer identifiers.
  • Stable device identifiers.
  • Source identifier plus browser identity.
  • Well-defined session fields.

Examples of weak key fields:

  • Request timestamps.
  • Values that are often blank.
  • Values that change on every request.
  • Fields that are too broad on their own, such as only the request path.

Where the field list comes from​

The field list in the Entities builder is tenant-specific. Esper exposes the fields currently available for this tenant, including:

  • Captured fields.
  • Derived fields.
  • Action fields.

If a field you expect is missing, contact your Esper administrator or support team.

API contract​

GET /tenants/{tenant_id}/entity-definitions
POST /tenants/{tenant_id}/entity-definitions
PATCH /tenants/{tenant_id}/entity-definitions/{entity_definition_id}
DELETE /tenants/{tenant_id}/entity-definitions/{entity_definition_id}