Person profiles and properties

Person profiles are collections of properties about the users behind the events. You can use these person properties to better capture, analyze, and utilize user data.

For example, you can create filters or cohorts based on person properties, which can then be used to create insights, feature flags, and more.

By default, PostHog's client-side SDKs will send anonymous events, meaning that your users will not have a person profile, unless you call .identify(), .set(), or another method that uses person profiles. You can change this by setting your snippet or frontend SDK initialization's person_profiles value to always

For backwards compatibility, PostHog's server-side SDKs will send identified events, meaning that your users will have a person profile. You can override this by changing a server-side SDK or API event's $process_person_profile property to false.

Note: Capturing identified events and setting person properties creates a person profile. Under our current pricing, anonymous events can be up to 4x cheaper than identified events (due to the cost of processing them), so it's recommended only to capture identified events when needed.

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'

Further reading

See our full documentation on persons and person properties for more details.