Fields
Register the fields of an event type to define the data contract accepted by POST /events. The fields determine what the platform validates on submission, what it ignores, and what becomes available for metrics and monitors.
Field settings
When registering a field in the admin panel, you define:
| Setting | What it defines |
|---|---|
| Field ID | identifier used in the API payload |
| Name and description | labels displayed in the panel |
| Data type | expected format for the value |
| Property type | how the field is treated in modeling |
| Required | whether the field must be present in every event |
| Inheritance | whether the field is inherited by later posts under the same id |
| Display | how the value is presented in the panel |
| Status | whether the field is active or inactive |
The form groups these settings into Behavior (required, sensitivity, inheritance and status), Format (precision, display and size limits) and Tracking.
Data types
A field takes one of these data types, chosen at creation:
| Data type | What it stores | Property type |
|---|---|---|
| Text | free text, with a configurable maximum size | dimension or measure |
| List | one value among the registered items | dimension or measure |
| Integer | number with no decimal places | measure |
| Decimal number | number with fixed precision and scale, suited to monetary values | measure |
| Floating point number | fractional number with no fixed precision, such as a score or a rate | measure |
| Boolean | true or false | measure |
| Date and time | an instant in ISO 8601 format, comparable by period | measure |
Important notes
- A text field has a Maximum size in bytes, from 1 to 1024, with a default of 48. Larger values are rejected, or cut when Truncate automatically is on.
- A list field accepts up to 100 registered items, and refuses any value outside them. Truncation does not apply: a cut value would stop matching the item.
- In a decimal field, precision goes up to 12 digits and scale up to 4 places, both fixed after creation.
- In a floating point field, the Decimal places apply to display only and can be changed later.
Suggestions
When registering the items of a list field, the platform presents the received values that have no corresponding item yet, covering the current month and the previous one. Selecting a value opens the new-item row already filled in, leaving only the label to enter.
The suggestion stops being displayed once the item is registered. It returns if the item is removed while the field keeps receiving the value. Sensitive fields generate no suggestions.
Item appearance
Each item of a list field accepts a visual mark, presented in the icon column of the item listing: a color, an icon from the catalog, or the logo of a brand, located by name or by website address. The mark tells the items apart at a glance, for example the issuers or the payment methods of a field. The mark is optional and takes no part in validating the received value. The account uses the same feature.
Property type: dimension or measure
Each field also receives a property type:
- dimension: represents a characteristic of the event used for segmentation;
- measure: represents a variable value used in consolidations.
The choice exists only in text and list fields. The other data types are always measure, as the table above shows.
The property type determines which metrics and monitors can be configured over the field later.
Inheritance
A field with Inheritance on is inherited by later posts that use the same id and do not provide the field. Turn inheritance on for the fields that describe the entity and arrive only in the first post, such as the customer or the merchant. Leave inheritance off for the fields that hold only for the post that carried them, such as the step or the response code of that attempt.
Turning inheritance off takes effect on the next post, including for values already accumulated. The full mechanism is described in Inheritance between events under the same id.
Value display
The panel can present a field differently from the stored value. The display is visual only: the recorded value, the filters and the comparisons in rules keep using the original value.
| Display | Applies to | Result |
|---|---|---|
| Original value | any field | the value as received |
| Country (ISO 3166) | text | the country name and flag, in place of the code |
| Card issuer | integer | the issuer name, in place of the identifier |
| ASN provider | integer | the provider name, in place of the number |
| Duration | integer | readable time, such as 3.5s or 2d 1h |
The duration display has a setting of its own: the time unit the value is stored in, among milliseconds, seconds and minutes. Without the unit, 3500 can be either three and a half seconds or almost an hour. The default is milliseconds, the unit of the tracking fields.
Track time in value
Mark a discrete field (list or boolean) as trackable. The platform starts recording the time each entity stays in each value of that field: the duration of an order in pending, the elapsed time of an account under block.
When tracking is enabled, the platform provisions two derived fields. The derived fields work like any other field of the event type, including in metrics, filters and rules:
| Derived field | Property type | Content |
|---|---|---|
Previous <field> | dimension | value the entity was in before the change |
Time in previous <field> | measure | duration of the period closed by that change |
Two settings accompany tracking:
- Breakdown dimensions: discrete fields by which the open measures can be segmented, such as the provider or the merchant. Only these fields can be used as a dimension in an open tracking metric.
- Tracking retention: how long an entity may stay in a value before it stops being tracked. Configure your process’s deadline: an entity that exceeds it was abandoned rather than held, and counting it distorts the open measures. Left blank, 90 days apply, which is also the ceiling.
An event type accepts at most 2 trackable fields. Disabling tracking stops the recording and preserves the derived fields and the metrics built on them. Re-enabling tracking reuses the same fields.
Tracking applies from the moment it is enabled and does not reprocess history. The same applies to a breakdown dimension added later: entities already open remain without it until they change value.
Validation on event submission
When receiving events via POST /events, the platform applies the field contract with the following rules:
- missing required fields cause rejection;
- values outside the expected type cause rejection;
- inactive fields can remain in the payload, but their values are ignored;
- unknown fields can be ignored or rejected, depending on the event type configuration.
Best practices for modeling fields
- Define stable and semantic IDs from the start.
- Start with a lean set of essential fields.
- Use list fields when there is a controlled set of values.
- Avoid creating redundant fields for the same concept.
- Periodically review unused fields.
Restrictions and lifecycle
Some settings are structural. Plan these settings at creation time:
- the field ID cannot be changed after registration;
- the data type cannot be changed after registration;
- the property type cannot be changed after registration;
- for decimal fields, precision and scale are fixed after creation;
- list field items are managed after the field is created;
- the event type has a limit of up to 100 fields.
Fields managed by the platform, such as those provisioned by tracking or by rules, cannot be removed. The name and the description of these fields accept changes, so they appear in the panel with your operation’s terminology.
Removing a field can fail if it is in use by metrics, for example in dimensions or aggregations.