Contentful

Sync data to Contentful entries via the Content Management API (CMA). Use Zeotap to push product listings, articles, localized pages, or any structured content to your Contentful space.

Prerequisites

• A Contentful account with an active space
• A content type defined in the target space and environment
• A Content Management API (CMA) personal access token with write access
• The space ID, environment ID, and content type ID

Authentication

Contentful uses a Content Management API personal access token for authentication.

1. Log in to your Contentful web app
2. Navigate to Settings > CMA tokens (or API keys > Content management tokens)
3. Click Generate personal token
4. Give the token a descriptive name (e.g., “Zeotap Sync”)
5. Copy the token (it starts with CFPAT-) and paste it into the Management Token field in Zeotap

Required Permissions

• The token must have write access to the target space and environment
• Ensure the token owner’s role includes permissions for the target content type

Configuration

Supported Operations

Sync Modes

Audience Sync Modes

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

Features

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

How It Works

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

1. Insert mode: Each row is sent as a new entry via POST /spaces/{space_id}/environments/{environment_id}/entries or PUT with a specific entry ID if a primary key is provided
2. Update mode: Each row is sent as a PUT request to the existing entry endpoint with the X-Contentful-Version header for optimistic locking
3. Upsert mode: Rows with a primary key (Contentful entry ID) are updated; rows without one are created as new entries with an auto-generated ID

Field Format

Contentful entries use a locale-aware field structure. Zeotap wraps each mapped field value in the default en-US locale:

{
  "fields": {
    "title": { "en-US": "My Article" },
    "body": { "en-US": "Content here..." }
  }
}

If your space uses multiple locales, map separate source columns for each locale-specific field (e.g., title_en, title_de).

Versioning and Optimistic Locking

Contentful uses version numbers for optimistic concurrency control. When updating an existing entry, Zeotap first fetches the current entry to obtain its version, then sends the update with the X-Contentful-Version header. If another process updates the entry between the fetch and the write, the update fails and is reported as a row error.

Publishing

Entries created or updated via the CMA are saved in draft status by default. They are not automatically published. After the sync completes, you can publish entries manually in the Contentful web app or set up a webhook/automation to auto-publish.

Rate Limits

The Contentful CMA enforces rate limits per access token:

If a 429 Too Many Requests response is received, Zeotap automatically retries with exponential backoff, respecting the Retry-After header (specified in seconds or as a timestamp in the X-Contentful-RateLimit-Reset header).

Best Practices

• Use meaningful entry IDs: For upsert and update modes, use a stable identifier from your source data (e.g., a product SKU or article slug) as the primary key. This becomes the Contentful entry ID.
• Match field IDs exactly: Destination field names must match the Contentful content type field IDs (not display names). Field IDs are typically camelCase (e.g., heroImage, publishDate).
• Test in a sandbox environment: Create a non-master environment for testing syncs before writing to production content.
• Keep content types focused: Sync to a single content type per destination. Create separate destinations for different content types.
• Monitor version conflicts: In high-concurrency scenarios, update failures due to version conflicts are expected. Retry on the next sync run.

Troubleshooting

Authentication failed: invalid management token

Verify that the management token is correct and starts with CFPAT-. Tokens can be regenerated in Settings > CMA tokens. Revoked or expired tokens return a 401 error.

Space not found

The space ID is incorrect or the space has been deleted. Find the correct space ID in Settings > General settings in the Contentful web app. The space ID is an alphanumeric string.

Environment not found

The environment ID is incorrect, the environment does not exist, or it has been deleted. Use master for the default environment. Check available environments in Settings > Environments.

Content type not found

The content type ID does not exist in the specified environment. Open Content model in the Contentful web app to verify the content type ID. Content type IDs are case-sensitive.

Version mismatch errors

An entry was modified between the version fetch and the update request. This is expected in environments with concurrent editors. The affected row is reported as a failure and will be retried on the next sync run.

Rate limited (429 Too Many Requests)

Your API token’s rate limit has been exceeded. Zeotap retries automatically with exponential backoff. For high-volume syncs, consider spacing out sync runs or using a dedicated API token.

Field validation errors

Contentful validates entry fields against the content type schema. Common causes of validation failures include:

• Sending a value that doesn’t 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 or link field values

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

Entries not appearing on the website

Entries created via the CMA are saved in draft status. They must be published before they appear in content delivered via the Content Delivery API (CDA). Publish entries manually or set up automation in Contentful.