Pendo

Send visitor metadata, account metadata, and track events to Pendo for product experience analytics. Sync your warehouse data to enrich Pendo visitor and account profiles or send server-side track events.

Prerequisites

• A Pendo account with API access enabled
• A Pendo Integration Key with write permissions
• A Track Event Shared Secret (required only for Track Events)
• Custom metadata fields pre-configured in Pendo for any fields you plan to sync

Authentication

Pendo uses an Integration Key for API authentication. When sending Track Events, an additional Track Event Shared Secret is required.

Integration Key

1. In Pendo, navigate to Settings > Subscription Settings
2. Under App Details, locate the Integration Key section
3. Copy your Integration Key (or generate a new one if needed)
4. Enter the Integration Key in Zeotap when configuring the destination

The Integration Key is used for visitor and account metadata API calls. Keys do not expire by default.

Track Event Shared Secret (Track Events only)

1. In Pendo, navigate to Settings > Subscription Settings > Applications
2. Select your application
3. Under App Details > Basic settings, click Show next to Track Event shared secret
4. Copy the shared secret and enter it in Zeotap

The Track Event Shared Secret is a separate credential required only when the Object Type is set to Track Events. It is different from the Integration Key.

Configuration

Target Settings

Supported Operations

Sync Modes

Pendo metadata endpoints are idempotent upserts. Sending metadata for an existing visitor or account updates it; sending metadata for a new ID creates a new record. Track events are append-only and support both insert and upsert modes.

Audience Sync Modes

Pendo does not have a list or audience membership API, so audience sync modes are not supported.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Visitor Metadata: visitorId, accountId

Account Metadata: accountId, name

Track Events: visitorId, accountId, event, timestamp, properties, context_ip, context_user_agent, context_url, context_title

All additional mapped fields are included as custom metadata values (for visitor/account) or event properties (for track events).

How It Works

Visitor and Account Metadata

Zeotap sends metadata to Pendo using the bulk metadata endpoints:

• Visitor: POST /api/v1/metadata/visitor/bulk
• Account: POST /api/v1/metadata/account/bulk

Each request contains up to 1,000 records. The payload is a JSON array where each object includes the identifier (visitorId or accountId) and a values object with the metadata fields.

[
  {"visitorId": "user-123", "values": {"plan": "pro", "role": "admin"}},
  {"visitorId": "user-456", "values": {"plan": "enterprise", "role": "viewer"}}
]

Track Events

Track events are sent individually to POST /data/track. Each event includes the visitor ID, event name, timestamp, optional properties, and context.

{
  "type": "track",
  "event": "Feature Activated",
  "visitorId": "user-123",
  "accountId": "acct-456",
  "timestamp": 1524069206000,
  "properties": {"feature": "dashboard"},
  "context": {"ip": "1.2.3.4", "userAgent": "Mozilla/5.0"}
}

Error Handling

Zeotap automatically retries failed requests with exponential backoff for transient errors (HTTP 429, 5xx). Non-retryable errors are reported per-row in the sync run results.

Rate Limits

Pendo enforces rate limits on the REST API but does not publish exact numeric thresholds. HTTP 429 responses indicate rate limiting. Zeotap handles this automatically with retry and backoff. Best practices:

• Use the bulk metadata endpoints (up to 1,000 records per request) instead of per-record calls
• Track events are limited to one event per visitor per second
• Monitor sync run logs for rate limit errors and adjust sync frequency if needed

Best Practices

• Pre-configure custom metadata fields in Pendo before syncing. Only fields defined in Pendo’s metadata schema are accepted.
• Use custom metadata fields for CRM data (not auto fields). Auto fields like email and name may be overwritten by the Pendo snippet on the next page load.
• Keep property names under 32 characters, using only letters, numbers, and underscores. Do not start or end names with double underscores.
• Track event properties are limited to 512 bytes per event. Keep property payloads concise.
• Prefer upsert mode for metadata syncs. Pendo metadata endpoints are naturally idempotent.

Troubleshooting

Authentication failed: invalid integration key

Verify your Integration Key in Pendo > Settings > Subscription Settings > App Details. Ensure the key has write permissions and has not been regenerated since configuration.

Metadata fields not appearing in Pendo

Custom metadata fields must be pre-configured in Pendo before they can be written via the API. Navigate to Settings > Subscription Settings > Metadata and add the fields you plan to sync.

Visitor metadata being overwritten

Auto metadata fields (like email, firstName) set via the API may be overwritten by the Pendo snippet when the visitor next loads a page. Use custom metadata fields for data synced from your warehouse.

Track events not visible in Pendo

Track events can take a few minutes to process and appear in Pendo analytics. Verify the visitorId matches a known visitor and the timestamp is a valid Unix timestamp in milliseconds.

Rate limit errors (HTTP 429)

Zeotap retries rate-limited requests automatically with exponential backoff. If errors persist, reduce sync frequency or batch size. Pendo does not publish specific rate limit thresholds.

Properties exceeding size limit

Track event properties are limited to 512 bytes. Reduce the number or size of property values. Consider sending only essential properties and using metadata for larger datasets.

Account metadata not updating

Verify the accountId field is correctly mapped and matches existing account IDs in Pendo. New accounts are created automatically, but metadata updates require the exact account ID.