Sync visitor metadata from a Salesforce report

Last updated: October 20, 2026 11:59

Use a Salesforce report as the source of your Salesforce visitor sync, so the report decides which records sync to Pendo and which of their fields become visitor metadata, including fields from related records like the contact's account.

Overview

By default, the Salesforce integration syncs visitor metadata from every record of the Salesforce object you connect, like Contact. For more information, see Set up "pull" data syncs in Set up the Salesforce integration for Pendo.

With a Salesforce report as the source, instead of every record of the object, you build a report in Salesforce and connect it to Pendo. On every sync, Pendo:

Reads the report's filters to decide which records sync.
Updates the visitor that matches each record.
Copies the report columns you select into Pendo as visitor metadata, including fields from related records, like Account Name or Account Owner. These fields are stored on the visitor. They don't change which Pendo account the visitor belongs to.

You can then build segments from that metadata and use them across Pendo, for example to target guides or Orchestrate emails and journeys.

Pendo can also create a visitor for each record that doesn't match one. This lets you reach people who never sign in to your app, like executive sponsors and billing contacts. For more information, see Create visitors for records not found in Pendo.

The sync only pulls data from Salesforce into Pendo. It doesn't change any Salesforce records.

How the report sync works

What happens to each report row

On every sync, Pendo runs your report's definition as a Salesforce query and processes each row.

Row	What Pendo does
Matches an existing visitor	Updates that visitor's Salesforce metadata.
Doesn't match a visitor	Skips the row. If visitor creation is on, creates a visitor instead.
Has an empty unique identifier	Skips the row.
Shares its unique identifier value with other rows	Uses one of the rows and skips the others. You can download a list of the skipped rows from the sync results.

A row matches a visitor through the unique identifier you set up: a Pendo visitor field, like Visitor ID or email address, paired with a report column that holds the same value.

How Pendo reads your report

Pendo reads the report's definition, not the rows you see when you run it. It turns the report's columns and filters into a Salesforce query and runs that query on every sync as the connected Salesforce user, which is the user you authenticated the integration with. This means:

Show Me is ignored. The sync includes every record the connected Salesforce user can see that matches the report's filters, regardless of the report's Show Me setting, like "My contacts". To limit which records sync, add a filter to the report.
The report's sort order is ignored. Pendo syncs every matching row.
Row limits aren't supported. You can't use a report with a row limit (Top N).
Edits take effect on the next sync. Pendo reads the report again on every sync and recalculates relative dates, like NEXT 90 DAYS.

When syncs run

Pendo syncs once a day, between midnight and 6 AM in your subscription's time zone. You can also start a sync at any time. Every sync reads the whole report, not only the rows that changed.

After a sync, updated values appear on an individual visitor's details page right away. Visitor lists and totals take about 15 minutes to update.

When a record leaves the report

The sync never deletes visitors. If a record no longer matches the report's filters, Pendo stops updating that visitor, but the visitor and its last synced metadata stay in Pendo.

Because of this, a narrow report can leave visitors with old values. For example, a contact whose account renewed keeps the old renewal date. To keep fields current, use broad report filters, like every contact at active accounts, and apply narrower conditions in your Pendo segments.

Prerequisites

To sync from a Salesforce report, you need:

Pendo admin access. You must be an admin in your Pendo subscription.
The Salesforce integration. The integration must be authenticated in Settings > Metadata. For more information, see Set up the Salesforce integration for Pendo.
Salesforce permissions for the connected user. The Salesforce user the integration authenticates with must have the API Enabled permission, Read access to the report's base object and every field in the report, and access to the folder where you save the report. Records this user can't see don't sync.
A unique identifier. Decide which Pendo field and which Salesforce field identify a person in both systems. The Salesforce field must hold text or a number. If you plan to create visitors, see How created visitors get their Visitor ID before you decide.

Note: If you already sync visitors from a Salesforce object, the report replaces that object as the source. Keep your current unique identifier and include its Salesforce field as a column of the report. Every field you already map into Pendo must also be a column of the report. Visitors whose records aren't in the report stop updating.

Set up a report sync

Step 1. Build the report in Salesforce

A Salesforce admin usually completes this step.

In Salesforce, go to Reports and select New Report.
Select a report type, like Contacts & Accounts or a custom report type whose only object is Contact, then select Start Report. For other supported types, see Report requirements.
Keep the report format Tabular or Summary. Matrix and Joined reports aren't supported.
Add these columns:
- The field you selected as the unique identifier, like Email. It must be a field of the record itself, not of a related record.
- Every other field you want in Pendo, including related fields like Account Name. Pendo reads values only from the report's columns.
- If you already sync visitors from a Salesforce object, every field you already map into Pendo.
Add filters for the records you want to sync.
Check the report's standard date filter, like "Created Date". It applies to the sync, so make sure it doesn't exclude records you want.
Save the report in a folder that the connected Salesforce user can access.
Copy the report ID from the report's URL. It's the 15- or 18-character value that starts with 00O, for example 00O5j000004xL9tEAE.

Step 2. Connect the report in Pendo

In Pendo, go to Settings > Metadata and select the Visitor-level data tab.
In the Salesforce Visitor Integration section, select Set up Mapping.
Under Source, select Salesforce report.
In the Salesforce report ID field, enter the report ID.
Review the report details that Pendo shows: the report's name, the object its rows come from, and how many filters it has. If Pendo can't use the report, a message explains why and names the filter or column to change. Fix the report in Salesforce, then enter the ID again.
For Pendo Field, select the visitor field to match on, like Visitor ID or email address. If you already sync visitors from a Salesforce object, keep your current selection.
For Salesforce Field, select the report column that holds the same value. The list shows the report's columns from the record itself.
Select Save.
In Pick fields to add to Pendo, select the report columns you want as visitor metadata.
Select Done.

Step 3. Run the sync and check the results

In the Salesforce Visitor Integration section of the Visitor-level data tab, select Sync now, or wait for the nightly sync.
After the sync finishes, check the sync results in the same section. They show the report used as the source, how many Salesforce records Pendo found, and how many matched an existing visitor.
Open one of the matched visitors in Pendo and confirm that the mapped Salesforce fields have the values you expect.

Create visitors for records not found in Pendo

By default, the sync only updates visitors that already exist in Pendo. With visitor creation on, Pendo also creates a visitor for each record in the source that doesn't match one. This lets you include people who never sign in to your app in segments, Orchestrate emails, and journeys. Visitor creation works with a report or an object as the source.

Note: Visitor creation is available on request. To turn it on for your subscription, contact Pendo Support.

Important: The sync never deletes the visitors it creates, including when you turn visitor creation off or a record leaves the report. Check the report's filters before you turn on visitor creation.

How created visitors get their Visitor ID

The Pendo field you select as the unique identifier determines the Visitor ID that Pendo gives a created visitor:

Visitor ID. The created visitor's Visitor ID is the value in the report column. Select this only if that Salesforce field holds the exact value your app sends as the Visitor ID. When the person later signs in to your app, their activity is recorded on the same visitor.
Any other visitor field, like email address. The created visitor's Visitor ID is the record's Salesforce ID, and the report column's value is stored in the visitor field you selected. This visitor is a placeholder. When your app identifies a visitor with the same value in that field, Pendo merges the placeholder into that visitor after the next sync and removes the placeholder, so one person doesn't have two visitors.

If you're not sure which to use, select email address. This works when your app sends each visitor's email address to Pendo and each record in the report has its own email address.

What a created visitor includes

A created visitor includes the report columns you map into Pendo, stored as Salesforce metadata. Columns from a related record get a combined name. For example, the report column Account Name (Account.Name) becomes account_name, and Account Owner (Account.Owner.Name) becomes account_owner_name.

A created visitor has no app activity until the person signs in to your app. Pendo creates visitors only. It doesn't create Pendo accounts.

Turn on visitor creation

After Pendo Support turns on visitor creation for your subscription:

In Pendo, go to Settings > Metadata and select the Visitor-level data tab.
In the Salesforce Visitor Integration section, select Set up Mapping.
Select Create Pendo visitors for Salesforce Contacts not found in Pendo.
Select Save.
In Pick fields to add to Pendo, make sure the fields you need for segments and emails are selected. If you didn't match on email address, include Email.
Select Done.

After the next sync, the sync results also show how many visitors Pendo created, for example: "10 Salesforce records found; 0 matched in Pendo; 0 created."

Reach created visitors with Orchestrate

Build a segment with rules on the Salesforce fields you mapped, like the account's risk score or renewal date.
In the Orchestrate email or journey, select that segment.
In the segment settings of the email or journey, select Include recently created visitors without activity. If you don't select it, visitors with no app activity don't receive emails.
Set the email's Recipient metadata to a field that created visitors have a value in: the visitor email field you matched on, or the Salesforce email field you mapped.

Visitors created from Salesforce follow the same email rules as visitors created through CSV upload or the API. If a created visitor never signs in to your app, they stay eligible for 12 months after Pendo creates them. After that, Orchestrate stops emailing them until they have app activity. For the full rules, see Create and send an email and Create and customize a journey.

Example

Your Salesforce accounts have a renewal date field and a risk score field. You want to email the directors and VPs of at-risk accounts that renew in the next 90 days, including those who never sign in to your app.

In Salesforce, build a Contacts & Accounts report of the contacts you might email, for example contacts at active accounts whose title contains "Director" or "VP".
Add columns for the unique identifier, like Email, and for the account fields you want in Pendo, like Account Name, the risk score, and the renewal date.
Connect the report to Pendo, turn on visitor creation, and build a segment where the risk score is "High" and the renewal date is in the next 90 days.

After the next sync, each contact in the report has a Pendo visitor with those account fields. Because the report stays broad, the risk score and renewal date stay current, and the segment decides who gets each email.

Report requirements

Report format and type

	Supported	Not supported
Format	Tabular. Summary, which syncs like a tabular report: the row grouping is ignored, and every row is included, even with Show Details off.	Matrix, Joined
Report type	Contacts & Accounts. A custom report type whose only object is Contact. If your integration uses leads or a custom object for visitors, the Leads type (including Leads with converted lead information) or a custom type whose only object is that object. Any of these can be extended with a custom lookup. Contacts & Accounts leaves out contacts without an account, in Salesforce and in Pendo.	Types that pair each row with a record from a related list: the "with" types (like Contacts with Assets, or Opportunities with Contact Roles), the History types, and the Activities types. A custom type that joins a second object as rows.
Related fields	Fields reached through a lookup on the record, standard or custom: the contact's account (Account Name and any other account field), the account's owner (Account Owner), and the contact owner's role (Owner Role).	Fields of records in a related list, like a contact's cases, campaign memberships, or activities. A contact can have many of them, so Pendo can't read them as one column.

Pendo skips some columns with a note instead of an error: report-only calculations (converted currency, row counts, ages), bucket fields, row-level formulas, and fields the connected Salesforce user can't read. Using any of these in a filter causes an error.

Filters

	Supported	Not supported
Filter kinds	Field filters on the record's fields and on fields reached through a lookup, like account fields. Custom filter logic (AND, OR, NOT, and parentheses). The report's standard date filter (for example, "Created Date: Last 7 Days"), for every period, including combined ones like "Current and Previous FY".	Cross filters ("with" or "without" related records). Field-to-field filters: use a formula field instead.
Operators	equals, not equal to, less than, greater than, less or equal, greater or equal, contains, does not contain, starts with, includes, excludes	Text operators on a field that isn't text
Fields	Any field Salesforce can query on	Long text area, rich text, and encrypted fields. A report can filter on them, but a Salesforce query can't, so the filter causes an error that names the field. These fields can still be columns.

How Pendo reads filter values:

Picklists, including multi-select picklists, are matched by label. If a filter uses a picklist value that was later removed from the field, the sync stops with a message that names the value. To resume syncing, remove the value from the filter. Salesforce doesn't warn you about this, because the report keeps running and matches nothing on that value.
Numbers and currency are read as plain numbers. In a multi-currency Salesforce org, Pendo keeps the currency code, so a filter value of USD 1 is compared in US dollars.
Dates can be fixed dates, date-times, or any relative date the report builder offers (for example, THIS MONTH, NEXT 90 DAYS, 3 DAYS AGO, or THIS FISCAL QUARTER), evaluated in the connected Salesforce user's time zone.
The standard date filter covers the same days it does in the report. On date-time fields, day boundaries currently follow UTC. For more information, see Known limitations.

Troubleshooting

What you see	What to do
Enter a Salesforce report ID that's 15 or 18 characters.	Copy the ID from the report's URL in Salesforce. Report IDs start with 00O.
A message about a row limit, a Matrix or Joined report, a cross filter, a field-to-field filter, or an unsupported field	Change the report as described in Report requirements, save it, then enter the report ID again.
Pendo can't find or open the report	Check that the report is saved in a folder the connected Salesforce user can access.
This field is no longer in the Salesforce report. Select a different field.	The column you matched on was removed from the report. Add it back in Salesforce, or select a different field.
One or more mapped fields are no longer in the Salesforce report. To continue, remove or replace them.	A column you mapped into Pendo was removed from the report. Add it back in Salesforce, or remove or replace the mapping.
Pendo doesn't sync report rows without a value in [field name]	Some rows have no value in the unique identifier. Fill in the field in Salesforce, or add a filter that excludes empty values.
Duplicate entries found.	Select View list to download a list of the records Pendo skipped because they share a unique identifier value with another record. Fix the data in Salesforce or add a filter to the report.
The sync includes records that the report doesn't show you	The report's Show Me setting limits what you see, but Pendo syncs every record the connected Salesforce user can see. To limit which records sync, add a filter to the report, like a Contact Owner filter.
Pendo created fewer visitors than the report has rows	Rows that match an existing visitor update it instead of creating one, so check the matched count first. Then check for rows with an empty or shared unique identifier, and check that the connected Salesforce user can see every record in the report.
A created visitor doesn't receive Orchestrate emails	Check that Include recently created visitors without activity is selected, that the email's Recipient metadata field has a value for the visitor, and that the visitor was created less than 12 months ago or has app activity.

For other sync issues, see Troubleshoot the Pendo Salesforce integration.

Known limitations

One source for your visitor sync. The report replaces the Salesforce object as the source of your visitor sync. You can't use both.
No account affiliation. Account fields from the report are stored as visitor metadata. They don't link visitors to Pendo accounts.
Visitors only. Visitor creation creates visitors. Pendo doesn't create accounts from Salesforce.
No deletion. The sync doesn't delete visitors that leave the report.
Date-time boundaries in UTC. On a date-time field, the standard date filter is measured in UTC days, not in the connected Salesforce user's time zone. Records within a few hours of the start or end of the range might sync even though the report excludes them, or the reverse.