Metadata configuration in Pendo allows you to enrich your analytics and create meaningful segments. Metadata includes information about your visitors and accounts, such as user role, account type, subscription revenue, and more.
You can send metadata into Pendo through your install script (agent) or integrations like Salesforce and HubSpot. Once received in Pendo, metadata must be configured to behave correctly across analytics, segmentation, and reporting.
There are three main steps to configuring your metadata:
- Send metadata to Pendo. Add metadata fields through your install script or integrations. 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.
- Assign data types to your metadata fields. Set the correct format for each metadata field, such as text, number, boolean, or date.
- Assign metadata mappings. Link metadata fields to standardized concepts like display name, email, revenue, and account type.
For an overview of metadata structure, data types, and metadata mappings, see Metadata and data mappings.
Tip: While there's no enforced limit to the number of metadata fields you can pass into Pendo, we recommend being selective. Fewer fields improve search performance, loading times, and overall data governance.
View your metadata
You can view and manage metadata fields in Settings > Metadata. The page separates fields into three tabs:
- Visitor-level data
- Account-level data
- Parent Account Metadata (if enabled)
Metadata is collected under Visitor IDs and Account IDs, allowing you to organize, segment, and analyze user behavior in Pendo based on these attributes.
Each field in the Fields table includes:
- Group. Source of the metadata, such as agent or Salesforce. For more information, see Understand metadata groups in this article.
- Enable Historical. Shows whether historical tracking is turned on. For more information, see Enable historical metadata in this article.
- Display Name. Label shown throughout the Pendo UI.
- Field Name. Original name passed from your source system.
- Type. Assigned data type, such as text or number. For more information, see Metadata and data mappings in Pendo.
- Example. A sample value from recent data, if available.
Admins can update display names, assign data types, and map fields to standard concepts like revenue or account type in the Mappings table.
Tip: If you're not an admin user, you can instead go to https://app.pendo.io/metadata. 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.
Understand metadata groups
Visitor-level and account-level data have the following metadata groups associated with them.
Agent (install script)
Agent metadata is passed from your product through the install script, commonly referred to as "the snippet", and it updates when users interact with your product.
You can edit the display names for these fields, but not original field names.
After you initially install Pendo or after you make any changes to your install script, we recommend reviewing your agent metadata on the Metadata 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 integration
These metadata fields are pulled in from Salesforce through our integration and aren't editable from the Metadata page. This is only an option if the Salesforce integration is enabled. For more information, see Salesforce integration with Pendo.
HubSpot integration
These metadata fields are pulled in from HubSpot through our integration and aren't editable from the Metadata page. This is only an option if the HubSpot integration is enabled. For more information, see Two-way HubSpot integration with Pendo.
Segment integration
These metadata fields are pulled in from the Segment.com integration and aren't editable from the Metadata page. This is only an option if the Segment.com integration is enabled. For more information, see Send Twilio Segment data to Pendo.
Custom metadata
Use custom metadata fields when the data you want to send to Pendo isn't available through the agent or an integration.
To get started, an admin must first create custom metadata fields in Settings > Metadata. After the field is added, you can populate it with values for specific visitors or accounts. For detailed instructions, see Manage custom metadata fields.
Note: Before sending data through the API, we recommend first adding the metadata field in the Pendo UI and assigning the correct data type. If you skip this step, the field defaults to the string data type, which can limit its use in segments. If data has already been sent for a non-string metadata field that wasn't initially created in the UI, update the data type in Settings > Metadata, then resend the data through the API for the changes to take effect.
Default fields
Default metadata is automatically generated by Pendo when visitors interact with your product. These metadata fields don't appear on the Metadata page, but the values are used in some calculations and populate on the details pages for specific visitors and accounts.
Default visitor metadata includes:
- First visit
- Last visit
- 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
Metadata fields in Pendo must meet specific naming and formatting requirements to work properly across analytics and segmentation.
- Field names can only include letters, numbers, and underscores (_).
- Field names must start with a letter or underscore. For example, if you have a metadata field named "360score", you must add a letter or underscore as the starting character.
- Spaces and special characters aren't supported and will prevent the field from being created.
If you can't find a metadata field when creating segments or reports, check that the field name follows these syntax rules.
Date and time fields
If you send date metadata to Pendo (whether agent, custom, Salesforce, HubSpot, or Segment), it must use the ISO8601 W3C format (for example, 2006-01-02T15:04:05.999-05:00).
If you need a different date format, contact Pendo Support. For a full list of supported date formats, see the Engage API documentation.
Language fields
The default language metadata field is reserved for the visitor's browser language, automatically captured by the agent.
If you're sending your own language metadata to Pendo (for example, from Salesforce or as custom metadata), you must use a different field name to avoid conflicts.
Pendo uses the default language field to localize your guides and Resource Centers. To set a different metadata field for localization, go to Settings > Subscription settings > Applications > select an application > Localization Settings > Language Preference Metadata.
Map your metadata
Metadata mappings connect your custom fields to standard Pendo attributes, allowing for consistent labeling and behavior across the platform, like for guide targeting, filtering, hover cards, and reporting.
You can find these mappings in Settings > Metadata, under the Visitor-level data and Account-level data tabs. Use the Mappings table to assign the appropriate metadata field to each standard mapping.
Note: The metadata field must already exist in the Fields table to appear in the dropdown.
The only available visitor-level mapping is Email, which is used in Listen to send update emails and to help uniquely identify visitors by email address. For more information, see Send update emails.
Account-level mappings include several fields:
- Display name. Replaces the default Account ID as the label shown across Pendo, including filters, dropdowns, and account hover cards.
- Website. Maps to the account's website domain.
- Revenue. Assigns a numeric revenue value to each account. First select the account currency, then choose the metadata field that contains the revenue amount.
- Account type. Categorizes accounts into lifecycle stages. After selecting the appropriate field, you can assign multiple values that represent prospects, customers, and churned accounts.
Enable historical metadata
By default, visitor and account metadata reflect only the most recent values passed to Pendo. To track how metadata changes over time, you can enable historical metadata for up to 25 fields in your subscription.
When enabled, these fields become global event properties, allowing Pendo to capture their values at the time of each event.
Note: Historical metadata isn't available for default values of Visitor ID and Sample Group, list-type fields, or metadata from Segment.com.
For more information, see Historical metadata.
Audit your metadata
As your application evolves, it's important to audit your metadata regularly to identify duplicates, outdated fields, or opportunities to clean up unused data. The following resources can help you make informed decisions:
- Use the Metadata page to see which fields are in use.
- See our linked API documentation to learn which segments, guides, and reports are using a particular metadata field or to obtain a list of where all metadata fields are in use.
Update metadata
To manually update metadata for a visitor or account after Pendo is initialized, use the updateOptions function. For more information, see our agent API documentation.
Delete agent or custom metadata
Subscription admins can delete agent or custom metadata through the Metadata page. To remove 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.
After deletion, the metadata field is removed from the list and no longer available for segmentation or filtering.
Note: If you delete an agent field from the Pendo UI but continue to send it through your install script, Pendo still receives the data but doesn’t process it. The field is scrubbed at the time of ingestion and doesn’t appear in segments, reports, or visitor and account details. If you later undelete the field, only data collected before the deletion is restored.
Deleted fields aren't automatically restored, even if re-added later with the same name. To restore a deleted field, contact Pendo Support.