FirstSpirit

Sync data to the FirstSpirit CaaS (Content as a Service) platform via its REST interface. Use Zeotap to push structured content or audience membership as JSON documents into a CaaS database and collection, so the FirstSpirit CMS can render and personalize pages against fresh, first-party data.

Prerequisites

A FirstSpirit / CaaS Platform instance (FirstSpirit Cloud or self-hosted CaaS)
A CaaS API Key with write access to the target database
The CaaS base URL, the target database (project store), and the target collection

Authentication

FirstSpirit CaaS authenticates each request with an API Key sent as a Bearer token.

Open the CaaS admin database and locate the apikeys collection (global keys), or the apikeys collection of the specific database (local keys).
Create an API Key with write permission on the target database.
Copy the value of the key’s key attribute.
Paste it into the API Key field in Zeotap.

Every request Zeotap sends carries the header Authorization: Bearer <api-key>.

Required Permissions

The API Key must grant write access to the target database and collection.
Local (per-database) keys are evaluated before global keys; either kind works as long as it covers the target database.

Configuration

Field	Type	Required	Description
CaaS Base URL	Text	Yes	The base URL of your CaaS Platform REST interface, without a trailing path (e.g. `https://your-project.caas.e-spirit.cloud`).

Target Settings

Field	Type	Required	Description
Database	Text	Yes	The CaaS database (tenant/project store) — the first path segment of the CaaS URL scheme.
Collection	Text	Yes	The collection that receives documents. Conventionally the FirstSpirit project UUID plus a preview/release state (e.g. `<uuid>.preview.content`).

Supported Operations

Sync Modes

Mode	Supported	Description
Insert	Yes	Creates documents. With a primary key, the key becomes the document `_id` (`PUT`); without one, CaaS generates the id (`POST`).
Update	Yes	Partially updates an existing document by id (`PATCH`, requires a primary key).
Upsert	Yes	Creates or replaces a document by id (`PUT`).
Mirror	—	Not supported for plain data syncs. Use upsert for incremental content syncs, or an audience sync for membership mirroring.

Audience Sync Modes

Mode	Supported	Description
Add	Yes	Writes one document per audience member, keyed by the member’s primary key (`PUT`).
Upsert	Yes	Same as add — the `PUT` by id is idempotent.
Remove	Yes	Deletes the member’s document by id (`DELETE`). A document that is already absent is treated as removed.
Mirror	Yes	Uses the per-run diff to `PUT` added/changed members and `DELETE` removed members.

Features

Field Mapping: Yes — map source fields to the JSON document properties written to CaaS.
Schema Introspection: No — CaaS collections are schemaless JSON stores, so document properties are defined by your field mapping.

How It Works

Each row becomes a single JSON document, addressed by the row’s primary key (the CaaS document _id) under the three-part CaaS URL scheme https://<base-url>/<database>/<collection>/<document>:

Insert / Add / Upsert: PUT /{database}/{collection}/{id} creates or replaces the document. When a row has no primary key (data syncs only), Zeotap POSTs to the collection so CaaS assigns an id.
Update: PATCH /{database}/{collection}/{id} merges the mapped fields into the existing document.
Remove: DELETE /{database}/{collection}/{id} removes the document; a 404 (already absent) is treated as success.
Mirror: rows the diff marks as removed are deleted; all other rows are PUT.

Documents are sent one per request because CaaS addresses documents individually by id. Transient failures (429, 5xx) are retried with exponential backoff; per-document failures are reported as row errors without failing the whole batch.

Rate Limits

CaaS enforces per-key rate limits. Zeotap writes documents sequentially (the connector is not concurrency-safe) and automatically retries 429 Too Many Requests and 5xx responses with exponential backoff, honoring any Retry-After header.

Best Practices

Use a stable primary key: For upsert, update, remove, and mirror, pick a stable identifier from your source (e.g. a customer id or content slug) so it maps to a predictable CaaS _id.
Separate preview and release: Target the collection matching the CaaS state you want to feed (...preview.content vs ...release.content); create separate destinations for each.
Keep documents focused: Map only the fields the CMS needs. CaaS collections are schemaless, so unmapped source columns simply won’t appear.
Test connectivity first: The connection test verifies the base URL, API key, database, and collection before you run a sync.

Troubleshooting

Authentication failed: invalid API key

The API Key is wrong, revoked, or lacks permission on the target database. Regenerate or re-scope the key in the apikeys collection and confirm it has write access.

Database not found

The base URL or database name is incorrect. The database is the first path segment of the CaaS URL scheme; verify it against your CaaS instance.

Collection access errors

The API Key does not cover the target collection, or the collection name is wrong. A collection that does not yet exist is created lazily on first write, so a missing collection is not fatal during the connection test.

Documents not appearing on the website

CaaS stores the document immediately, but the FirstSpirit CMS renders from a specific collection and state (preview vs release). Confirm the sync targets the collection your delivery layer reads.

Rate limited (429 Too Many Requests)

The API Key’s rate limit was exceeded. Zeotap retries automatically with exponential backoff. For very large audiences, expect the sync to pace itself.

Update reports missing primary key

update and remove require a primary key to address the document. Map a source column as the sync’s primary key, or use upsert/insert which can create documents without one.