Person properties

Person properties enable you to capture, manage, and analyze specific data about a user. You can use them to create filters or cohorts, which can then be used in insights, feature flags, surveys, and more.

Person properties are stored on person profiles. When setting properties, a person profile is created if it doesn't already exist.

How to set person properties

The recommended way to set person properties is to send a $set event with a $set property:

posthog.capture(
    '$set', 
    { 
        $set: { name: 'Max Hedgehog'  },
        $set_once: { initial_url: '/blog' },
    }
)

You can also set person properties when you call the identify method:

posthog.identify(
  'distinct_id',  // Replace 'distinct_id' with your user's unique identifier
  { email: 'max@hedgehogmail.com', name: 'Max Hedgehog' } // optional: set additional person properties
);

Person property values can be strings, booleans, numbers, objects, or arrays. For objects and arrays, you can use HogQL to access nested properties in PostHog.

Note: Person properties are set in the order the events are ingested, and not according to event timestamps. Since we typically ingest events as soon as we receive them, you only need to take this into consideration when you're importing historical data.

What is the difference between set and set_once?

Using set replaces any property value that may have been set on a person profile. In contrast, set_once only sets the property if it has never been set before.

set is typically used for properties that may change over time – e.g., email, current plan, organization name. set_once is typically only used for information that is guaranteed to never change – e.g., the first URL a user visited, or the date a user first logged in.

For example:

posthog.capture(
    'event_name', 
    { 
        $set: { name: 'Max Hedgehog'  },
        $set_once: { initial_url: '/blog' },
    }
)
posthog.capture(
    'event_name', 
    { 
        $set: { name: 'Mr. Fox'  },
        $set_once: { initial_url: '/pricing' },
    }
)
// name: 'Mr. Fox'
// initial_url: '/blog'

How to remove person properties

Similarly to how you set properties, you can use $unset to remove properties from person profiles with any event and including an array of property keys:

posthog.capture(
    'event_name', 
    { 
        $unset: ['email'],
    }
)

How to view and edit a person profile and properties

To view the person profile and properties for a particular person, go to Persons & Groups in the PostHog app. Then, click on any person in the list to view their properties.

On a person's property list, you can add properties to them by clicking the "New property" button, and then adding a key, type, and value. You can also delete a custom property for a user by clicking the red garbage bin icon on the right side of the property listing.

Person display name

The display name is the person property value shown in the PostHog UI to represent a user. It is their person distinct_id by default, but can be configured in project settings.

Default person properties

PostHog attempts to set the following properties for all users when using the posthog-js library or JavaScript snippet:

GeoIP Properties

By default, the GeoIP plugin is turned on for all PostHog projects. This adds the following properties to all events.