Appcues

Sync user profile attributes and events to Appcues to power in-product onboarding flows, tooltips, checklists, and launchpads. Zeotap pushes data from your warehouse directly into Appcues via the Appcues Public API v2, making warehouse-derived attributes immediately available for flow targeting and segmentation.

Prerequisites

• An Appcues account with administrator access to Studio
• An Appcues Account ID (visible in Studio under Account > Account Details)
• An API Key and API Secret pair generated from Studio Account > API Keys
• User identifiers (user_id) that match the values identified via your Appcues SDK (Appcues.identify(userId))

Authentication

Appcues uses HTTP Basic Authentication with an API Key and API Secret pair. The account_id is used as a URL path component for every request and is not part of the credential material.

1. Log in to Appcues Studio at studio.appcues.com 
2. Navigate to Account > API Keys
3. Click Create New API Key and copy both the API Key and API Secret
4. In Zeotap, enter:
   • Account ID — your Appcues account identifier
   • API Key — the public half of the key pair
   • API Secret — the secret half (shown only at creation time)

Keep the API Secret confidential. Regenerate the key pair from Appcues Studio if it is ever exposed.

Configuration

No additional configuration fields are required beyond authentication.

Target Settings

When Object Type is “User Profiles”

Each row is sent as a PATCH request to the Appcues user profile endpoint. Profiles are upserted — created if the user does not yet exist and merged with existing attributes if they do. Profile updates are synchronous and immediately available for flow targeting.

When Object Type is “Events”

Each row is sent as an individual POST request to the Appcues user events endpoint. Events carry a name, timestamp, and an optional attributes object and are available in Appcues Studio analytics and event-triggered flows.

Supported Operations

Sync Modes

The Appcues profile endpoint is inherently an upsert (PATCH merges into existing records). Zeotap accepts both Upsert and Insert modes; at runtime both produce the same API call.

Audience Sync Modes

Appcues does not expose a list, segment, or tag membership API. Audience membership in Appcues is computed from user profile attributes and events — control it by syncing attributes (e.g., plan_name, onboarded_at) with the User Profiles object type and building audience-like segments inside Appcues Studio.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

User Profiles

Events

How It Works

User Profile Syncs

1. Zeotap extracts user data from your model or audience
2. Each row is sent individually as PATCH /v2/accounts/{account_id}/users/{user_id}/profile
3. The request body is the flat set of mapped attributes (everything except user_id)
4. Appcues merges the attributes into the existing user profile, creating the profile if it does not exist
5. Updated attributes are available for flow targeting immediately

Event Syncs

1. Zeotap extracts event data from your model
2. Each row is sent individually as POST /v2/accounts/{account_id}/users/{user_id}/events
3. The request body contains name (from event_name), optional timestamp, and attributes
4. If an attributes JSON column is mapped, its contents are used directly; otherwise any unmapped columns are collected into the attributes object
5. Events appear in Appcues analytics and may trigger event-based flows

Rate Limits

Appcues does not publish numeric rate limits for the Public API. HTTP 429 responses indicate throttling; Zeotap retries automatically with exponential backoff via its HTTP client. For very large syncs, consider reducing concurrency or spreading syncs over time. If you regularly encounter 429 responses, contact Appcues support to discuss your volume.

Best Practices

• Align the user_id values in Zeotap exactly with the identifier passed to Appcues.identify(userId) — mismatched identifiers create orphan profiles
• Prefer User Profiles syncs to enrich attributes used for flow targeting, and Events syncs for backend-only events that clients cannot emit
• Keep profile payloads under a few hundred attributes per user; very wide payloads slow down sync and clutter Studio
• Use ISO-8601 timestamps for the timestamp field on events — other formats are rejected
• Start with a small-sample sync to verify identifiers and attribute names before running a full backfill
• Rotate API Key / API Secret pairs periodically and whenever staff with access leave the team

Troubleshooting

Authentication failed (HTTP 401 / 403)

Verify that the API Key and API Secret are entered correctly and have not been revoked in Studio Account > API Keys. Both halves of the key pair are required — the Account ID alone is not a credential. If the pair has been lost, generate a new one and update the destination.

User profiles not appearing in Studio

Confirm that the user_id field is mapped and contains non-empty values, and that those values match what your Appcues SDK sends via Appcues.identify(userId). Mismatched identifiers produce orphan profiles that are created but never linked to in-app user sessions.

Events not appearing

Ensure both user_id and event_name are mapped and non-empty. Check that timestamp is an ISO-8601 string. Events appear in Studio’s event analytics with a short processing delay.

Rate limit errors (HTTP 429)

Appcues throttles under heavy traffic. Zeotap retries automatically. If errors persist, reduce sync frequency, shrink the selected audience, or contact Appcues support for guidance on sustained high-volume ingestion.

404 Not Found on every request

Verify that the Account ID is correct — it is part of the URL path for every call. The Account ID is shown in Studio under Account > Account Details, and it is not the same as your organization name or subdomain.

Connection test succeeds but syncs still fail

The Appcues Public API does not provide a lightweight read-only validation endpoint, so the connection test only validates that all three credential fields are present. Full credential validation happens on the first sync. If the connection test passes but syncs fail with 401, re-generate and re-enter the API Key / API Secret pair.