Help Center

Overview

Every contact in Userorbit carries two kinds of data: properties that describe who the contact is, and events that record what the contact has done. Together, properties and events give you a complete picture of each person and power the targeting, segmentation, and personalization features across the platform.

Default contact properties

Userorbit creates the following properties automatically for every contact:

• name — The contact's display name, set when you call identify or import the contact.
• email — The contact's email address. Used for email messaging and as a natural lookup key.
• external_id — The unique identifier you assign from your own system when you call identify.
• avatar_url — A URL pointing to the contact's profile picture, typically pulled from Gravatar or passed explicitly.
• created_at — The timestamp when the contact first appeared in Userorbit, whether through the script, API, or import.
• last_seen — The timestamp of the contact's most recent session or API activity. Updated automatically.
• first_seen — The timestamp of the very first interaction recorded for this contact.
• session_count — The total number of sessions attributed to this contact.
• browser — The browser name detected from the contact's user agent string.
• os — The operating system detected from the contact's user agent string.
• country — The country resolved from the contact's IP address during their most recent session.
• city — The city resolved from the contact's IP address.

Custom properties

Beyond the defaults, you can attach any number of custom properties to a contact. Custom properties are defined by you and can hold strings, numbers, booleans, or dates. Common examples include:

• plan — The pricing plan the user is on (e.g., Free, Pro, Enterprise).
• company — The name of the organization the user belongs to.
• role — The user's role within their team (e.g., Admin, Member).
• signup_source — How the user discovered your product (e.g., Google, referral, Product Hunt).

Set custom properties by passing them in the identify call, through the REST API, or via a CSV import. Once a custom property has been set on at least one contact, it becomes available as a filter and segmentation criterion everywhere in Userorbit.

Tracked events

Events represent discrete actions a contact takes. Each event has a name and an optional set of metadata key-value pairs. Events are recorded by calling the track method in the Userorbit script or by sending them through the API.

Example events:

• feature_activated with metadata { "feature": "reports" }
• subscription_upgraded with metadata { "from": "free", "to": "pro" }
• support_ticket_created with metadata { "priority": "high" }

Events are timestamped automatically and appear on the contact's activity timeline in chronological order.

How properties and events are used across the platform

• Segmentation — Build segments using property filters (e.g., plan is Enterprise) or event conditions (e.g., performed feature_activated in the last 7 days).
• Targeting — Target messages to contacts matching specific property values or who have (or have not) performed certain events.
• Personalization — Insert property values into message templates using merge tags like {{name}} or {{company}}.
• Analytics — Aggregate events to measure feature adoption, conversion rates, and engagement trends.

Best practices

• Keep property names lowercase and use underscores instead of spaces for consistency.
• Send properties and events as early as possible in the user journey so targeting rules can evaluate them immediately.
• Avoid high-cardinality event metadata — store identifiers and categories rather than free-form text.