Appcues User Management API Guide

Auth method: HTTP Basic Auth (API Key + Secret)

Setup steps

1. Log in to studio.appcues.com and navigate to Settings > Integrations > API Keys.
2. Click 'Create new key', provide a friendly name, and select the desired permission level (e.g., Publisher or Admin).
3. Copy both the API Key and API Secret immediately - the secret is shown only once.
4. Attach credentials to every request using HTTP Basic Auth: concatenate API_KEY:API_SECRET, Base64-encode the string, and pass it as the Authorization header, or use curl's -u API_KEY:API_SECRET flag.
5. Note: The Legacy API Key (used for SDK installation) is separate from v2 API keys and cannot be deleted or disabled.

Required scopes

Track user activity (events + profile update) - v1

• Method: POST
• URL: https://api.appcues.com/v1/accounts/{account_id}/users/{user_id}/activity
• Watch out for: Auth on v1 uses the Legacy API Key (not the v2 key/secret pair). If user_id does not exist, a new user is created automatically.

Request example

curl https://api.appcues.com/v1/accounts/123/users/456/activity \
  -X POST -H "Content-Type: application/json" \
  -d '{"request_id":"abc123","events":[{"name":"clicked widget","timestamp":1452854179}],"profile_update":{"plan":"pro"}}'

Response example

true

Get end user profile - v2

• Method: GET
• URL: https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/profile
• Watch out for: Returns the most recently seen profile properties; does not guarantee real-time freshness for bulk-imported data.

Request example

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/profile \
  -u API_KEY:API_SECRET

Response example

{"user_id":"USER_ID","properties":{"plan":"pro","role":"admin"}}

Update end user profile (synchronous) - v2

• Method: PATCH
• URL: https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/profile
• Watch out for: Synchronous - immediately available for targeting. Bulk imports via POST /import/users are asynchronous and may take minutes.

Request example

curl -X PATCH https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/profile \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '{"plan":"enterprise","role":"admin"}'

Response example

{"status":200}

Get end user events - v2

• Method: GET
• URL: https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/events
• Watch out for: Returns most recent events only; for full historical export use POST /export/events.

Request example

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/events \
  -u API_KEY:API_SECRET

Response example

{"events":[{"name":"flow_completed","timestamp":"2024-01-10T12:00:00Z"}]}

Track user event (synchronous) - v2

• Method: POST
• URL: https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/events
• Watch out for: Immediately available for flow targeting, but takes several minutes to appear in insights/charts.

Request example

curl -X POST https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/events \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '{"name":"feature_used","timestamp":"2024-01-10T12:00:00Z"}'

Response example

{"status":200}

Bulk import user profiles - v2

• Method: POST
• URL: https://api.appcues.com/v2/accounts/{account_id}/import/users
• Watch out for: Asynchronous - returns a job_id. POST body limit is 20MB; file upload limit is 200MB. Accepts CSV or NDJSON.

Request example

curl -X POST https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/users \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/x-ndjson' \
  -d '{"user_id":"u1","plan":"pro"}'

Response example

{"job_id":"abc-123","job_url":"https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/abc-123","status":202}

Create segment - v2

• Method: POST
• URL: https://api.appcues.com/v2/accounts/{account_id}/segments
• Watch out for: Segment creation only creates the container; a second call to /segments/{segment_id}/add_user_ids is required to populate it with user IDs.

Request example

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '{"name":"Power Users","description":"Users on pro plan"}'

Response example

{"id":"-Mv-owpQUFrI5RFTdh5_","name":"Power Users","url":"https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-Mv-owpQUFrI5RFTdh5_"}

Add user IDs to segment - v2

• Method: POST
• URL: https://api.appcues.com/v2/accounts/{account_id}/segments/{segment_id}/add_user_ids
• Watch out for: Accepts only user_id column in CSV. Adding the same user ID multiple times is harmless. Updates may take a few minutes to take effect.

Request example

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/add_user_ids \
  -u API_KEY:API_SECRET \
  -F file=@user_ids.csv

Response example

{"job_id":"c5abb279-85d1-4c8b-9930-f37a0460a82f","status":202,"title":"Accepted"}

• Rate limits: Requests are throttled per API key under heavy traffic. HTTP 429 is returned when throttled. No publicly documented numeric rate limit tiers found in official docs.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Official docs state HTTP 429 is returned when 'requests from this API key are being throttled due to heavy traffic.' No specific numeric limits or rate-limit headers are documented publicly. Retry logic is recommended.
• Pagination method: none
• Default page size: 0
• Max page size: 0
• Pagination pointer: Not documented

• Webhooks available: Yes
• Webhook notes: Appcues supports outbound webhooks configured via Studio (Settings > Integrations > Webhooks). When a subscribed event occurs, Appcues pushes a real-time HTTP POST to the configured URL. Webhooks can be filtered to specific flows or experience types. An optional account secret key enables HMAC-SHA256 signature verification via X-Apc-Signature and X-Apc-Timestamp headers.
• Alternative event strategy: Zapier integration available for no-code webhook routing. Appcues.on() JavaScript SDK listener for client-side event handling. Raw data export to Amazon S3 or Google Cloud Storage available on Enterprise plans.
• Webhook events: appcues:flow_started (Web Flow Started), appcues:flow_completed (Web Flow Completed), appcues:flow_skipped (Web Flow Skipped), appcues:flow_aborted, appcues:form_field_submitted (Web Flow Form Submitted), appcues:checklist_started, appcues:checklist_completed, appcues:checklist_dismissed, appcues:checklist_skipped, appcues:mobile_flow_started, appcues:mobile_flow_completed, appcues:mobile_flow_skipped, appcues:pin_interacted (Pin click/hover), appcues:nps_score (NPS submitted), appcues:segment_entered, custom event (any custom event tracked via SDK or API)

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not supported on any plan
• Endpoint: Not documented

Limitations:

• SCIM is explicitly not supported by Appcues.
• SSO (SAML) is available on Enterprise plans via Okta, Entra ID, and OneLogin, but there is no SCIM provisioning/deprovisioning.
• User provisioning must be handled via the Public API or manual Studio administration.

Three primary automation scenarios are well-supported by the API:

• Bulk user property import for targeting: POST a CSV or NDJSON file to /v2/accounts/{account_id}/import/users. The operation is asynchronous - capture the job_id from the 202 response and poll /v2/accounts/{account_id}/jobs/{job_id} for completion. For immediate targeting availability, use the synchronous PATCH /v2/accounts/{account_id}/users/{user_id}/profile instead.

• Programmatic segment creation: Two calls are required - POST to /v2/accounts/{account_id}/segments to create the container, then POST a CSV of user_id values to /v2/accounts/{account_id}/segments/{segment_id}/add_user_ids. Duplicate IDs are safe but not deduplicated; allow a few minutes for propagation before using the segment in flow targeting.

• Real-time flow event ingestion via webhook: Configure outbound webhooks in Studio (Settings > Integrations > Webhooks) to push appcues:flow_completed, appcues:nps_score, appcues:segment_entered, and other events to any HTTP endpoint. Enable HMAC-SHA256 signature verification via X-Apc-Signature and X-Apc-Timestamp headers by setting an account secret key - store it securely server-side.

Bulk-import historical user properties for targeting

1. Generate an API Key+Secret in Studio (Settings > Integrations > API Keys) with Publisher permission.
2. Prepare a CSV or NDJSON file with a user_id column plus any custom property columns (e.g., plan, role, company).
3. POST the file to https://api.appcues.com/v2/accounts/{account_id}/import/users with -u API_KEY:API_SECRET and the appropriate Content-type header (text/csv or application/x-ndjson).
4. Capture the job_id from the 202 response and poll GET /v2/accounts/{account_id}/jobs/{job_id} until status is complete.
5. Verify properties appear on user profiles in Studio before using them in flow targeting rules.

Watch out for: Bulk imports are asynchronous and may take several minutes. If immediate targeting availability is needed, use the synchronous PATCH /users/{user_id}/profile endpoint instead.

Create a segment from a list of user IDs and target a flow

1. POST to /v2/accounts/{account_id}/segments with a JSON body containing name and description to create the segment container.
2. Save the segment id from the response.
3. Prepare a CSV file with a single user_id column listing all user IDs to include.
4. POST the CSV file to /v2/accounts/{account_id}/segments/{segment_id}/add_user_ids using multipart form upload (-F file=@user_ids.csv).
5. Wait for the job to complete (poll job_url or wait a few minutes), then use the segment in Studio flow targeting.

Watch out for: The add_user_ids endpoint only accepts user_id values - no other properties. Adding duplicate IDs is safe but does not deduplicate.

Receive real-time flow completion data via webhook

1. In Studio, go to Settings > Integrations > Webhooks and click to create a new webhook.
2. Enter the destination URL (your server endpoint or a Zapier/Make webhook URL).
3. Select the 'Web Flow Completed' event (and optionally filter to a specific flow ID).
4. Optionally add an account secret key to enable HMAC-SHA256 signature verification via X-Apc-Signature and X-Apc-Timestamp headers.
5. Enable the webhook from the '...' menu on the webhook list page.
6. On your server, parse the incoming JSON payload to extract user_id, flowId, flowName, and any form response data.

Watch out for: Webhooks can only be created and edited by users with Admin permissions in Studio. Signature verification requires storing the account secret key securely on your server.

The absence of SCIM means the API is the only programmatic path for user lifecycle management, but the API itself is not a drop-in SCIM replacement. There is no endpoint to list all internal team members, assign roles, or deprovision Studio users - those actions remain UI-only in Settings > Teams.

Rate limiting is undocumented numerically; HTTP 429 is returned under heavy traffic with no Retry-After header, so exponential backoff must be implemented defensively. Bulk import and export operations are asynchronous and can take several minutes, making them unsuitable for real-time provisioning triggers without a polling or job-status layer.

The EU data residency base URL (api.eu.appcues.com) differs from the US default - all official documentation examples use the US URL, so EU-region accounts must override the base URL explicitly in every integration.

Identity Verification (HMAC user ID signing) uses a fourth distinct credential - the SDK Authentication Key - separate from both the Legacy API Key and v2 Key+Secret pairs, adding credential management surface area.