MongoDB
Write data to MongoDB collections via the Atlas Data API. Use Zeotap to sync customer profiles, enriched data, or model results into MongoDB as JSON documents without requiring a driver or direct database connection.
Prerequisites
- A MongoDB Atlas cluster with the Data API enabled
- A Data API key generated from the Atlas UI
- The Data API base URL for your cluster
- The target database and collection created in your Atlas cluster
Authentication
MongoDB uses API Key authentication via the Atlas Data API.
- Log in to your MongoDB Atlas account
- Navigate to Data API in the left sidebar
- Click Create API Key and give it a descriptive name
- Copy the generated API key and store it securely — you will not be able to view it again
- Enter the API key in Zeotap when configuring the destination
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Cluster URL | Text | Yes | The MongoDB Atlas Data API base URL for your cluster (e.g. https://data.mongodb-api.com/app/data-xxxxx/endpoint/data/v1) |
| Data Source | Text | Yes | The Atlas cluster name used as the dataSource parameter in API requests (e.g. Cluster0). Found in your Atlas Data API configuration |
| Database | Text | Yes | The MongoDB database name to write to |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Collection | Text | Yes | The target MongoDB collection name |
Supported Operations
Sync Modes
| Mode | Supported | Description |
|---|---|---|
| Upsert | Yes | Updates existing documents by _id or inserts new ones using updateOne with upsert: true |
| Insert | Yes | Inserts new documents using insertMany. Fails on duplicate _id values |
| Update | Yes | Updates existing documents by _id using updateOne. Does not insert new documents |
| Mirror | — | Not supported |
Audience Sync Modes
MongoDB does not support audience sync modes. Use standard sync modes to write audience membership data as document fields.
Features
- Field Mapping: Yes — map source columns to MongoDB document fields
- Schema Introspection: No — MongoDB is schema-flexible; define destination fields manually
Required Mapping Fields
| Field | Description |
|---|---|
_id | Unique identifier for the MongoDB document. Used as the match key for upsert and update operations |
Default Destination Fields
| Field | Type |
|---|---|
_id | string |
email | string |
name | string |
phone | string |
created_at | timestamp |
updated_at | timestamp |
How It Works
Zeotap uses the MongoDB Atlas Data API to write documents over HTTPS. No MongoDB driver or direct database connection is required.
Insert Mode
Documents are sent in batches of up to 1,000 using the insertMany Data API action. Each batch is a single HTTP POST request containing all documents as a JSON array.
Upsert and Update Modes
Each document is sent as an individual updateOne request. For upsert, the request includes upsert: true, which creates the document if no match is found by _id. The update uses a $set operator to set or overwrite all mapped fields.
Error Handling
- Transient errors (HTTP 429, 5xx) are retried with exponential backoff up to 3 times
- Per-document errors are tracked and reported in the sync run summary
- Failed documents do not block the rest of the batch from being processed
Rate Limits
The Atlas Data API enforces the following limits:
- Request size: 16 MB maximum per request
- Throughput: Varies by Atlas tier; see your cluster’s Data API settings
- Concurrent requests: Limited by your Atlas project configuration
Zeotap respects rate limit responses (HTTP 429) and backs off automatically.
Best Practices
- Use
_idconsistently: Ensure the_idfield maps to a stable, unique identifier from your source data to enable reliable upserts - Prefer upsert mode: For most use cases, upsert is the safest sync mode — it handles both new and existing documents
- Monitor document size: MongoDB has a 16 MB document size limit. Avoid mapping large JSON blobs or arrays that could exceed this
- Create indexes: Add indexes on fields you query frequently in your MongoDB collection to maintain read performance as data grows
Troubleshooting
Authentication failed: invalid API key
Verify the Data API key is correct and has not been revoked. Generate a new key from the Atlas UI if needed.
API connectivity failed
Check that the Cluster URL is correct and includes the full path (ending in /data/v1). Ensure the Data API is enabled for your cluster in the Atlas UI.
insertMany failed: duplicate key error
This occurs when inserting documents with _id values that already exist in the collection. Switch to Upsert sync mode to update existing documents instead of failing.
updateOne failed: _id is required
Every document must have an _id field mapped for upsert and update modes. Ensure your field mapping includes a source column mapped to _id.
Request size exceeded
The Atlas Data API has a 16 MB request size limit. If you have very large documents, reduce the number of mapped fields or split the sync into smaller batches.
Slow sync performance
For large datasets, upsert and update modes send individual requests per document. Consider using insert mode for initial data loads, then switching to upsert for incremental syncs.