Configure visitor and account metadata

Last updated:

Visitor and account metadata are collected under Visitor and Account IDs to enrich your analytics and your options for guide targeting. You can leverage this metadata when you build segments and reports, and you can add and remove metadata over time. For guidance on sending us metadata, see Developer's guide to implementing Pendo using the install script or IT guide to deploying the Pendo Launcher, depending on your implementation method.

Regardless of how you send us metadata, you can view, configure, and manage your metadata on the Data Mappings page, which has a separate tab for Visitor Level Data and Account Level Data (and Parent Account Metadata if enabled). This is where Pendo admins can specify the type of data fields that are sent to Pendo. For more information, see Data mapping and data types in Pendo.

Tip: While there's no currently enforced limit to the amount of metadata fields you can pass into Pendo, we recommend being selective about which fields you include. This helps optimize search performance, loading times, and overall data governance.

View your metadata

Visitor and account metadata are different for every Pendo customer because not everyone sends the same metadata fields. Admin users can check the metadata being sent to Pendo in Settings > Data Mappings. The Data Mappings page is where you can see the names and types of data Pendo uses for analytics.


Tip: If you're not an admin user, you can instead go to The first dropdown menu lists all the metadata currently sent to Pendo. Selecting an item from the dropdown shows you metrics, such as how many unique values are being sent for that metadata field.

In the Account Level Data tab, you have the option to adjust your Account Display Settings at the top of the page, which determines the identifier value displayed within the account filter for each account. This allows you to replace the default Account ID with a more descriptive value, such as the Account Name or another identifiable metadata field. This change impacts the account dropdown filter across Pendo and the search results on the Accounts page. To modify this account identifier, select a new value from the Show Account name as dropdown list.


Understand metadata groups

Visitor-level and account-level data have the following metadata groups associated with them.

Agent metadata

Agent metadata is passed from your product through the install script, commonly referred to as "the snippet". You can update the display names for these fields, but the original field names can't change.

After you initially install Pendo or after you make any changes to your install script, we recommend reviewing your agent metadata on the Data Mappings page to ensure the fields exist and that the data types match what's sent through your install script.

If an agent metadata value is incorrectly populated, it updates the next time the visitor uses your application and passes the correct information. You can update agent metadata values through the API, but these values are overwritten the next time a value is passed through the install script.

Salesforce metadata

These metadata fields are pulled in from Salesforce through our integration and aren't editable from the Data Mappings page. This is only an option if the Salesforce integration is enabled. For more information, see Salesforce integration with Pendo.

HubSpot metadata

These metadata fields are pulled in from HubSpot through our integration and aren't editable from the Data Mappings page. This is only an option if the HubSpot integration is enabled. For more information, see HubSpot integration.

Segment metadata

These metadata fields are pulled in from the integration and aren't editable from the Data Mappings page. This is only an option if the integration is enabled. For more information, see integration overview.

Custom metadata

Use custom metadata fields if the data you want to add doesn’t fall into any of the above groups.

An admin must first add custom metadata fields in Settings > Data Mappings. After the field is added in Data Mappings, you can link the custom values to a visitor or account. To learn how to do this, see Update custom metadata fields.

Note: Before sending custom metadata through the API, we recommend manually adding the metadata field and assigning the correct data type on the Data Mappings page. If the field isn't first added in the Pendo UI, it defaults to the string data type, which can limit its use in segments. If data has already been sent through the API for a non-string metadata field that wasn't initially created in the UI, you must assign the correct type on the Data Mappings page and resend the data through the API for the new type to take effect.

Default metadata

Default metadata is automatically generated by Pendo when visitors interact with your product. These metadata fields don't appear on the Data Mappings page, but these values are used in some calculations and populate on the details pages for specific visitors and accounts.

Default visitor metadata includes:

  • First visit
  • Last list
  • Number of days active
  • Number of events
  • Time on site
  • Most recent browser version and name
  • Most recent operating system
  • Most recent server name

Default account metadata includes:

  • First visit
  • Last visit
  • Number of days active
  • Number of events
  • Number of visitors
  • Time on site

Format metadata correctly

Supported characters for metadata field names are letters, numbers, and underscores (_). Field names containing spaces or unsupported characters won't be created in Pendo.

Metadata fields must also begin with a letter or underscore. For example, if you have a metadata field named "360score", you can add a letter as the starting character or change it to "_360" to be supported.

If you find that you're unable to select a specific metadata field when creating segments or adding columns to a report in Pendo, verify that the field follows the required syntax.

Date and time fields

When adding any new type of metadata (agent, custom, Salesforce, HubSpot, or Segment) that's a date, Pendo uses the ISO8601 W3C (for example, 2006-01-02T15:04:05.999-05:00) format. Ensure you’re using this format before sending data into Pendo.

If you want to use a different date format, contact Pendo Support. Our Engage API documentation lists all supported date formats.

Language fields

The default language metadata field in Pendo is collected from the visitor's browser settings by the Pendo agent. If you pass language data with custom visitor metadata through the agent or through integrations like Salesforce, the custom language metadata field must use a name other than "language" since this name is reserved for browser language metadata and can't be replaced.

You can specify a different metadata field for language in your localization settings through Settings > Subscription Settings > Localization Settings.

Enable historical metadata

Visitor and account metadata always show the details associated with the last recorded event for a user. If you want to have historical context around user metadata, you can choose to enable historical metadata for up to five data mapping fields in your subscription.

When you enable historical metadata, it's considered a global event property, as it allows that data to function like an event property by capturing the value on every event at the time it occurred.

Note: You can't enable historical metadata for default values of Visitor ID and Sample Group, metadata with a list type, and metadata.

To learn more, see Historical metadata.

Audit your metadata

As your app and user base evolve over time, it's important to regularly audit your metadata. When you encounter the need to remove duplicate fields or gain insight into overall metadata field usage, the following resources can help you make informed decisions:

Update metadata

If you need to manually update metadata for a visitor or account after Pendo has been initialized, you can use the updateOptions function. For more information, see our agent API documentation.

Delete agent or custom metadata

Admin users can delete agent or custom metadata through the Data Mappings page. To delete a metadata field, hover over the field, select Remove, and then confirm the deletion. The confirmation prompt displays for a few seconds to prevent accidental deletions. If no confirmation occurs, the button reverts to the Remove state.

Once you confirm, the metadata field is removed from the list and is no longer available for use in segmentation.

Note: If you delete an agent field from the Pendo UI, but don't delete it from your install script, Pendo continues capturing the data but won't re-populate into the UI. To undo the deletion, contact Pendo Support.

Was this article helpful?
8 out of 21 found this helpful