Manage custom metadata fields

If you want to add data to Pendo that isn't passed in through the agent or an integration, you can use custom metadata fields to provide that data. You can then leverage this data to focus on more specific cohorts of users when creating reports or segments for guide targeting.

Step 1. Add custom metadata field

Before you can assign custom metadata values to your users, an admin user must first add the custom metadata field on the Data mappings page.

1. Go to Settings > Data mappings.
2. By default, you're directed to visitor-level metadata. If you want to add custom metadata fields for accounts or parent accounts, select the corresponding tab.
3. Find the bottom field in the Metadata table that has Add Custom Field as the Display Name.
4. Enter your preferred display name, select the appropriate Type from the dropdown menu (text, boolean, number, or date), and then select + Add.
   
   
   
   When added, the display name is copied over to the Field Name column and can't be changed. However, you can change the display name at any time.
5. Repeat steps 2 to 4 for each custom field needed.

After you add a custom field, you can find the field in a visitor or account's details page for a particular visitor or account under Details > Custom.

Step 2. Add custom values to users

After the field is added in Data mappings, you can add the custom values to a visitor or account. There are a few ways to add or update custom metadata values for visitors and accounts.

Update custom fields manually

You can manually update a custom metadata field for a single visitor and account by going to the visitor or account details page for a specific visitor or account. Open the top Details section, then locate the Custom section, and modify the relevant fields.

This method is useful if you only need to update a handful of fields to use in a segment.

Update custom fields with CSV upload

You can update multiple visitor or account records with a single CSV upload, up to 24 metadata fields for each file.

Note: It's important to ensure all Visitor IDs, Account IDs, and metadata fields appear in your file exactly the way they display in Pendo. If your file contains Visitor IDs or Account IDs that don't match existing visitors or accounts, this creates new records in Pendo. If your file contains metadata fields that don't match what's on the Data mappings page exactly, your CSV upload will fail.

1. Save a copy of our example CSV file, and use it to populate your data. You must be signed in to a Google account to save a copy.
   
   
   
   If you don't have a Google account, you can create your own file in your preferred text editor. If creating your own file, ensure that the first column header is visitorId and each subsequent column header contains each custom metadata field, similar to the example screenshot shown above.
2. If you're updating accounts instead of visitors, update the first column header to accountId. If you're updating parent accounts, update the first column header to parentAccountId instead.
3. Replace the example metadata field names in the subsequent column headers with the correct field names as they display on the Data mappings page. All Visitor IDs, Account IDs, metadata fields, and values are case-sensitive.
4. Add or remove additional columns as needed, ensuring that the metadata fields display exactly as they do in Data mappings.
5. After you update all necessary values, save your file in CSV format. If you're using Google Sheets, do this by selecting File > Download > Comma Separated Values (.csv).
   
   
   
   
6. Go to People > Visitors or People > Accounts, locate the bottom Visitors or Accounts list, and then select Upload CSV in the top-right corner of the table.
   
   
   
   
7. Select Choose File, select the saved CSV file on your device, and then select Upload File. It can take up to 15 minutes for the updated metadata values to display in Pendo.
8. Optionally, select the Manage columns icon in the top-right corner of the table, and add the relevant metadata fields as columns to your table.

Update custom fields with API

You can also make single or bulk updates to custom fields through our API.

Using an API tool like Postman, you can update a single record using our API endpoint. The API endpoint you use depends on the environment you access Pendo from. Refer to the provided table for the corresponding endpoint, then use the guidelines that follow.

• First, add your integration key in the Headers section of the API call next to x-pendo-integration-key. If you need an integration key, Pendo Admins can create one by navigating to Settings > Integrations > Integration Keys and selecting Add Integration Key. Select Allow Write Access so that you can properly push data to Pendo with the key.
  
  
  
  
• Next, fill out the Body of the request similar to the example shown below, ensuring that you replace john.doe@pendo.io with the appropriate Visitor ID, role with your custom metadata field, and Field Sales with your custom metadata value:
  

  [{
      "visitorId": "john.doe@pendo.io",
      "values": {
          "role": "Field Sales"
      }
  }]

  
  

If you want to update multiple Visitor IDs using the API, the required API call is similar to the one reviewed above for updating a single record. If the metadata you want to pass to Pendo lives in a different system and you don't have access to this data, you'll likely need help from your development team. For guidance, see our API documentation to Set Value for a Set of Agent or Custom Fields.