Planhat

Sync data to Planhat customer success objects. Use Zeotap to push company data, enduser profiles, assets, licenses, and other records into Planhat to power your customer success workflows.

Prerequisites

• A Planhat account with access to the API
• An API access token generated from a Private App in Planhat
• Knowledge of which Planhat object you want to sync data to (companies, endusers, assets, etc.)

Permissions

Your API access token permissions are configured at the Private App level in Planhat. Ensure the Private App has read and write access to the object types you plan to sync.

Authentication

Planhat uses a static API Access Token for authentication.

1. Log into your Planhat account
2. Navigate to Settings > Private Apps
3. Click Create Private App (or select an existing one)
4. Configure the appropriate permissions for the objects you want to sync
5. Generate an API access token from the Private App
6. Copy the token and paste it into the API Access Token field in Zeotap

The API access token does not expire and persists until you disable the Private App or remove the token.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Planhat does not have a native audience or list membership concept, so audience sync modes are not supported.

Features

• Field Mapping: Yes — map source columns to Planhat field names
• Schema Introspection: No — Planhat fields must be configured manually

Required Mapping Fields

Other object types do not have strictly required mapping fields, but should include at least one keyable field (externalId, sourceId, or _id) for update and upsert operations.

Default Destination Fields

Company

Enduser

Asset

How It Works

Zeotap writes data to the specified Planhat object via the Planhat REST API bulk upsert endpoint:

1. Bulk Upsert (PUT /{objectType}): Records are sent as a JSON array. Planhat automatically determines whether to create or update each record based on keyable matching.
2. Keyable Matching: For each record, Planhat checks for a match in this priority order: _id > sourceId > externalId. For endusers, email is also used as a keyable.
3. Batching: Zeotap chunks records into groups of up to 1,000 and sends them sequentially. Planhat supports up to 5,000 items per request, but smaller batches improve error isolation.

Error Handling

• The writer retries on transient errors (HTTP 429 rate limits and 5xx server errors) with exponential backoff.
• The Planhat bulk upsert response includes separate counts for created, updated, and errored records. Zeotap reports per-item errors where available.
• If a batch fails entirely, all records in that batch are marked as failed.

Rate Limits

Planhat enforces a soft limit of 200 API calls per minute to its main API. The hard limit is 150 requests per second with bursts of up to 50 parallel requests.

• Zeotap sends batches sequentially to stay well within these limits.
• Bulk upsert requests count as a single API call regardless of the number of records in the payload.
• For very large syncs, the 5,000-item-per-request limit and body size limit of 32 MB per request are the binding constraints.

Best Practices

1. Include keyable fields: Always include at least one keyable field (externalId, sourceId, or _id) in your field mapping for update and upsert modes. Without a keyable, Planhat cannot match records to existing data.
2. Use externalId for cross-system matching: If syncing from a warehouse or CRM, map your system’s unique identifier to Planhat’s externalId field for reliable upsert behavior.
3. Set the correct region: If your Planhat instance uses a regional URL (e.g., app-us1.planhat.com), configure the region field accordingly. Using the wrong region will cause API connectivity failures.
4. Map companyId for endusers: When syncing enduser records, include the companyId field to associate endusers with their parent company in Planhat. This is required for creating new endusers.
5. Test with a small batch first: Before syncing large datasets, run a test sync with a small number of records to verify field mapping and API connectivity.
6. Use Private App permissions: Scope your API access token’s permissions to only the object types needed for your sync. This follows the principle of least privilege.

Troubleshooting

Authentication failed: invalid API access token

Verify that your API access token is correct and that the associated Private App has not been disabled. Generate a new token under Settings > Private Apps if needed.

API connectivity failed

Check that the region is configured correctly. If your Planhat URL is app-us1.planhat.com, set the region field to us1. If you use the default app.planhat.com, leave the region field blank.

Records not updating (creating duplicates instead)

Ensure your records include at least one keyable field (_id, sourceId, or externalId) that matches existing records in Planhat. Without a keyable, Planhat treats every record as a new insertion.

Enduser creation failing

Enduser records require a companyId field to associate the enduser with a company. Verify that the companyId value corresponds to an existing company’s _id in Planhat.

Rate limited (HTTP 429)

Planhat enforces a soft limit of 200 API calls per minute. Zeotap retries automatically with exponential backoff. If you consistently hit rate limits, consider reducing sync frequency or contacting Planhat support to increase your quota.

Missing or incorrect field values

Planhat field names are case-sensitive. Verify that your field mapping uses the exact Planhat field names (e.g., externalId, not external_id or ExternalId). Refer to the Planhat API documentation for the correct field names for each object type.

Bulk upsert body too large

Planhat enforces a 32 MB limit on request bodies. If you are syncing records with very large payloads (e.g., records with many custom fields or large text values), reduce the batch size or trim field values before syncing.