Common Room

Sync contacts, member profiles, and activities to Common Room for community-led growth intelligence, signal tracking, and member engagement analysis. Zeotap pushes data from your warehouse into Common Room via their REST API, enabling you to enrich community member profiles with product usage data, firmographic attributes, and custom activity signals.

Prerequisites

• A Common Room account on a plan that includes API access
• An API token generated from the Common Room dashboard
• A Destination Source ID from an API signal configured in Common Room
• Contact email addresses that can serve as the primary identifier

Authentication

Common Room uses API Token authentication with Bearer tokens.

1. Log in to your Common Room account at app.commonroom.io 
2. Navigate to Settings > API Tokens
3. Click Create Token to generate a new API token
4. Copy the token immediately — store it securely as it may not be shown again
5. Paste it into the API Key field in Zeotap

Keep your API token secure. It provides access to read and write data in your Common Room workspace. Do not share it in publicly accessible areas.

Configuration

Setting Up the Destination Source ID

Before syncing data, you need to create an API signal source in Common Room:

1. In Common Room, navigate to Settings > Sources
2. Click Add Source and select API
3. Name your signal source (e.g., “Zeotap CDP Sync”)
4. Copy the Destination Source ID shown after creation
5. Paste it into the Destination Source ID field in Zeotap

Target Settings

When Object Type is “Contacts”

Contact data is sent to Common Room via the user endpoint. Each contact is created on first sync or updated if they already exist (upsert behavior), matched by email address. Standard fields like fullName, companyName, and social usernames are mapped directly, while additional fields are stored as custom properties.

When Object Type is “Activities”

Activities are sent individually to Common Room and appear on the member’s timeline. Each activity requires at least an email address to identify the member. Additional fields such as activityType, activityId, title, description, and occurredAt provide context for the activity.

Supported Operations

Sync Modes

Audience Sync Modes

Common Room segments are filter-based and computed dynamically — membership cannot be managed directly via the API. Use contact properties to control segment membership indirectly.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

How It Works

Contact Syncs

1. Zeotap extracts contact data from your model or audience
2. Each contact is sent individually to the Common Room user endpoint (POST /community/v1/source/{id}/user)
3. Contacts are matched by email address — new contacts are created, existing contacts are updated (upsert behavior)
4. Standard fields (name, company, social handles) are mapped to Common Room’s known fields
5. Additional mapped fields are passed through and stored as custom properties on the contact profile
6. Per-record errors are captured and reported individually

Activity Syncs

1. Zeotap extracts activity data from your model
2. Each activity is sent individually to the Common Room activity endpoint (POST /community/v1/source/{id}/activity)
3. The email field identifies the member, and additional fields provide activity context
4. Activities appear on the member’s timeline in Common Room under the API signal source
5. You can define custom activity types to categorize the activities you send

Rate Limits

Common Room enforces dynamic rate limits. As a general guideline:

• Recommended throughput: Up to 20 requests per second
• Rate limit response: HTTP 429 when limits are exceeded

Zeotap automatically handles rate limiting with exponential backoff and retries. Records are sent individually (no batch API is available), so large syncs may take longer to complete.

Best Practices

• Create a dedicated API signal source in Common Room for each Zeotap sync to keep data organized
• Ensure email addresses in your source data are accurate — Common Room uses email as the primary identifier for contact matching
• Use the Contacts object type to enrich member profiles with firmographic data, product usage metrics, and social handles
• Use the Activities object type to send backend events, product milestones, or custom signals that complement community activity data
• Map social handles (twitterUsername, githubUsername, linkedinUrl, etc.) to help Common Room auto-merge profiles across platforms
• Send companyName and titleAtCompany to improve Common Room’s organization intelligence and buyer signal detection
• Start with a small sync to verify data mapping before running full syncs
• Use the Upsert sync mode to keep contact profiles current without duplicating records

Troubleshooting

Authentication failed

Verify your API token is valid and has not been revoked. Tokens are managed in Settings > API Tokens in Common Room. If the token has expired or been deleted, generate a new one.

Contacts not appearing in Common Room

Ensure the email field is mapped and contains valid, non-empty email addresses. Common Room requires an email to create or match a contact. Check that the Destination Source ID is correct and corresponds to an active API signal source.

Activities not appearing on member timelines

Verify that the email field maps to an email address that exists in your Common Room workspace. If the member does not exist, the activity may be queued until the member is created. Check that the Destination Source ID is valid.

Rate limit errors (HTTP 429)

Common Room’s rate limits are dynamic but generally allow up to 20 requests per second. Zeotap retries automatically with exponential backoff. For persistent rate limit issues, reduce sync frequency or contact Common Room support to discuss higher limits.

Invalid Destination Source ID

If you see errors related to the source ID, verify that the API signal source still exists in Common Room under Settings > Sources > API. Source IDs are specific to a workspace — ensure you are using the correct workspace.

Duplicate contacts

Duplicate contacts occur when different email addresses refer to the same person. Common Room uses email as the primary deduplication key for API-synced contacts. Ensure your source data uses consistent email addresses. Common Room’s identity resolution will automatically merge profiles matched by social handles across other sources.

Custom properties not appearing

Custom properties (fields beyond the standard set) are stored on the contact profile but may take a moment to appear. Verify the field names do not conflict with Common Room’s reserved fields. Property values should be primitive types (strings, numbers, booleans) — complex objects may not be stored correctly.

Connection timeout errors

Common Room API calls have a 60-second timeout. If you see timeout errors, check your network connectivity and whether the Common Room API is experiencing downtime at status.commonroom.io . Transient timeouts are retried automatically.