Field reference

This page explains the values you can reference when building:

• Action expressions.
• Policy expressions.
• Entity match expressions.
• Entity key fields.

How the builder works

The builder separates three ideas:

1. Field type

This is a fixed menu of request features or an available field from the current catalog.

2. Field reference

This is freeform text only when the selected field type needs a specific name or path.

Examples:

• Header name: X-Foo
• Query parameter name: flow
• Cookie name: session_id
• Route parameter name: account_id
• Body data reference: body->user->email

3. Comparison value

This is freeform text when the condition compares the selected field to a value.

Examples:

• Value example: GET
• Value example: /login
• Value example: 123
• Value example: application/json

Request-native fields

Esper now evaluates request-native selectors directly. You do not need to know or guess an internal tenant field name to write conditions like:

• Request method equals GET.
• Header X-Foo is present.
• Query parameter flow equals signin.
• Body data reference body->user->email equals a@example.com.

Supported field types

Field type	What it means in plain language	Field reference needed?	Example
Request method	The HTTP method used by the request	No	GET
Request path	The URL path being requested	No	/checkout
Header	A specific HTTP header	Yes	X-Foo
Query parameter	A specific URL query parameter	Yes	flow
Cookie	A specific cookie value	Yes	session_id
Route parameter	A specific route parameter	Yes	account_id
Body data reference	A path into structured request body data	Yes	body->user->email
Source identifier	The sending integration or source	No	webapp
Observed timestamp	When Esper saw the request	No	2026-03-19T10:15:00Z
Client IP	The client IP address	No	203.0.113.5
User agent	The request user agent	No	Mozilla/5.0
Referrer	The referring URL	No	https://example.com/home
Body type	The request body content type	No	application/json
Available field	A captured, derived, or action field already exposed in the catalog	Choose from dropdown	request_path

What counts as an available field

The available field dropdown is still useful, but it is a separate concept from request-native selectors.

Available fields can be:

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

Captured fields

Captured fields come directly from request data that Esper records.

Examples:

• Example field: request_path
• Example field: http_method
• Example field: client_ip
• Example field: query_param_flow

Derived fields

Derived fields are computed from other values and usually have more business-friendly names.

Examples:

• Example field: email
• Example field: device_key
• Example field: composite_key

Action fields

Action fields are emitted by action matching and can be reused by entities and policies.

Examples:

• Example field: action_login
• Example field: action_checkout_complete

Examples in normal language

Action examples

• Request method equals POST.
• Header X-Risk equals high.
• Body data reference body->user->email is present.
• Client IP equals 203.0.113.5.

Policy examples

• Request path equals /checkout.
• Cookie session_id is present.
• Body type equals application/json.
• Referrer equals https://example.com/pricing.

Entity examples

• Identify an entity by email.
• Identify an entity by source_id plus client_ip.
• Identify an entity by an action field plus user_agent.

How to choose good key fields

Entity key fields should answer:

Which values remain stable when this is really the same actor or object?

Good candidates:

• Account identifiers.
• Stable device identifiers.
• Source identifier plus another stable value.
• Action fields when identity depends on behavior.

Usually poor candidates:

• Timestamps.
• Volatile request paths.
• Values that are blank too often.
• Values that change every request.

Guidance for non-technical operators

1. Start with the field type that matches how you think about the traffic.
2. Use a field reference only when the field type needs a name or path.
3. Use available fields when your team already exposed a meaningful business field.
4. Use request-native selectors when you want to describe the incoming request directly.

Related docs

• Entities
• Policies
• Actions
• Console Overview