Contentstack

Sync data to Contentstack entries via the Content Management API (CMA). Use Zeotap to push structured content such as articles, products, landing pages, or any custom content type to your Contentstack stack.

Prerequisites

• A Contentstack account with an active stack
• A content type defined in the target stack
• A Management Token with write access to the stack
• The stack API key and content type UID

Authentication

Contentstack uses a Management Token for authentication. Management tokens are stack-level read-write tokens that do not require user credentials.

1. Log in to the Contentstack dashboard 
2. Navigate to Settings > Tokens > Management Tokens
3. Click Add Token
4. Give the token a descriptive name (e.g., “Zeotap Sync”)
5. Select the appropriate permissions (read and write access to entries)
6. Click Save and copy the generated token
7. Paste the token into the Management Token field in Zeotap

Required Permissions

• The Management Token must have write access to entries in the target stack
• Ensure the token permissions cover the content type you intend to sync to

Configuration

Available Regions

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Contentstack does not support audience sync modes. Entries are not membership-based.

Features

• Field Mapping: Yes — map source fields to Contentstack field UIDs
• Schema Introspection: No — field names must be configured manually using Contentstack content type field UIDs

Required Mapping Fields

No required mapping fields. Map any source columns to Contentstack entry fields. Note that most content types require a title field.

How It Works

Zeotap writes data to Contentstack using the Content Management API (CMA):

1. Insert mode: Each row is sent as a new entry via POST /v3/content_types/{content_type_uid}/entries. Contentstack generates a unique entry UID.
2. Update mode: Each row is sent as a PUT request to the entry endpoint using the primary key as the entry UID. Rows without a primary key fail.
3. Upsert mode: Rows with a primary key (Contentstack entry UID) are updated via PUT. If the entry does not exist (404), a new entry is created. Rows without a primary key are created as new entries.

Entry Format

Contentstack entries are flat key-value objects. Zeotap maps each source column directly to a Contentstack field UID:

{
  "entry": {
    "title": "My Article",
    "body": "Content here...",
    "author": "Jane Doe"
  }
}

Field names must match the Contentstack content type field UIDs (not display names). Field UIDs are typically snake_case (e.g., hero_image, publish_date).

Locale Handling

All entries are written to the locale specified in the target settings (default: en-us). If your stack uses multiple locales, create separate destinations for each locale or use the locale field to control which locale receives the synced data.

Authentication Headers

Each API request includes:

• api_key header with the stack API key
• authorization header with the Management Token
• Content-Type: application/json

Rate Limits

The Contentstack CMA enforces rate limits per organization:

If a 429 Too Many Requests response is received, Zeotap automatically retries with exponential backoff.

Best Practices

• Match field UIDs exactly: Destination field names must match the Contentstack content type field UIDs (not display names). Field UIDs are typically snake_case.
• Include a title field: Most Contentstack content types require a title field. Ensure your mapping includes it.
• Use the correct region: Select the API base URL that matches the region where your stack is hosted. Using the wrong region will result in authentication errors.
• Use stable primary keys for upsert: For upsert and update modes, use a stable identifier from your source data as the primary key. This becomes the Contentstack entry UID for lookups.
• Test in a development stack: Create a separate stack or branch for testing syncs before writing to production content.
• Keep syncs scoped: Sync to a single content type per destination. Create separate destinations for different content types.

Troubleshooting

Authentication failed: invalid management token or stack API key

Verify that both the Management Token and Stack API Key are correct. Management tokens can be regenerated in Settings > Tokens > Management Tokens. Ensure the token has not been revoked or expired.

Stack not found or 412 error

The Stack API Key is incorrect or missing. Find the correct key in Settings > Stack in the Contentstack dashboard. The key typically starts with blt.

Content type not found

The Content Type UID does not exist in the stack. Open Content Models in the Contentstack dashboard to verify the UID. Content type UIDs are case-sensitive and typically use snake_case.

Entry not found during update

The primary key (entry UID) does not match an existing entry. Verify that the entry exists in the Contentstack dashboard. In upsert mode, a missing entry will be created instead.

Rate limited (429 Too Many Requests)

Your organization’s rate limit has been exceeded. Zeotap retries automatically with exponential backoff. For high-volume syncs, consider spacing out sync runs or reducing batch concurrency.

Field validation errors

Contentstack validates entry fields against the content type schema. Common causes include:

• Sending a value that does not match the expected field type (e.g., a string to a number field)
• Missing required fields defined in the content type
• Exceeding field length limits
• Invalid reference field values

Check the error message for the specific field and validation rule that failed.

Wrong region selected

If you receive unexpected authentication errors or timeouts, verify that the API Base URL matches the region where your Contentstack stack is hosted. Each region has a distinct API endpoint.

Entries not appearing on the website

Entries created or updated via the CMA may need to be published before they appear in content delivered via the Content Delivery API. Publish entries manually in the Contentstack dashboard or set up a workflow/webhook to auto-publish.