> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esperr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Field Reference

> Non-technical guide to the request fields you can reference in the builder.

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 `client_ip` plus `user_agent`.
* 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](./entities)
* [Policies](./policies)
* [Actions](./actions)
* [Overview](./intro)