Customer.io Integration

Use Customer.io when your lifecycle team wants Prevenue account intelligence, revenue signals, and lifecycle audiences inside Customer.io Journeys.

Open Settings > Integrations > Customer.io in Prevenue to connect credentials, send a test event, activate managed audiences, configure manual actions, and review recent activity.

Final docs URL: https://docs.prevenue.ai/integrations-and-sources/customerio-integration

What Prevenue sends

Prevenue uses the Customer.io Pipelines API for the base sync:

The setup test sends realistic sample data through Pipelines: an identify call for a sample person, a group call for a sample account, and a prevenue_signal_routed track call with example signal, recommendation, evidence, active audience, and account intelligence fields. The sample grow signal uses prevenue_signal_type = upgrade_ready, prevenue_signal_category = grow, prevenue_signal_priority = high, prevenue_score_key = expansion_readiness, and prevenue_score_label = Expansion ready. It proves the key, region, and endpoint can accept the same shape Prevenue uses for live Customer.io signal syncs.

Funnel and Signal delivery includes selected route channels, account scores, Event KPI rows, sentiment distributions, semantic/category counts, source counts, matched evidence count, and total events scored when available. The payload retains prevenue.automation.routing_key and prevenue.automation.name as compatibility fields. Read Signal Delivery Payloads for the shared contract.

Fields to map in Customer.io

Use the setup test to confirm these attributes appear on the sample person, account group, and prevenue_signal_routed event before building live Journeys.

The setup test intentionally uses normalized live-style values. For example, the account group should receive prevenue_score_label = ready, not a display phrase like Expansion ready.

Known prevenue_signal_type values include:

upgrade_ready
topup_to_plan
annual_ready
team_expansion
premium_feature_intent
limit_expansion
sales_assist
usage_drop_risk
login_drop_risk
downgrade_intent
cancel_intent
support_friction
contraction_risk
payment_risk_with_low_usage
trial_activated_not_paid
checkout_abandoned
free_user_high_usage
integration_connected_trial
team_invited_trial
event_grudging_dependency
event_friction_rescue
event_healthy_momentum_growth

watchlist exists inside Prevenue but watch signals are not routed to Customer.io live syncs.

Known prevenue_score_label values are:

ready
high
medium
low
critical
elevated
blocked

Credential checklist

Most teams should start with base sync, then add audience automation when they are ready for Prevenue-managed Customer.io segments.

The minimum working setup is Region + Pipelines API Key. Add Service Account Token + Workspace URL or ID when you want Prevenue to activate managed audiences, create Customer.io segments, reconcile managed static membership, or update manual segments.

When a Service Account Token is present, Prevenue exchanges it for a short-lived Customer.io bearer token, then validates it with a read-only workspace API request to the selected workspace. Managed audience and manual segment calls use Customer.io's regional workspace API host (us.fly.customer.io or eu.fly.customer.io). If the selected region, Workspace URL or ID, and Service Account Token do not belong to the same Customer.io workspace, setup fails before any managed audience is created.

Do not paste a Track API Site ID, Track API key, webhook signing secret, source ID, segment ID, campaign ID, broadcast ID, or message ID into the credential fields.

Find the Pipelines API Key

The Pipelines API Key is the key Prevenue uses to send identify, group, and track calls to Customer.io's Pipelines API.

1. In Customer.io, open Integrations.
2. Click Add Integration.
3. Choose Customer.io API.
4. Name the source something recognizable, like Prevenue production.
5. Send the Customer.io setup test if their setup flow requires it.
6. Copy the API key/write key from that source.
7. Paste it into Prevenue as Pipelines API Key.

Use the Pipelines key by itself, not a site_id:api_key pair. Customer.io's Pipelines API uses Basic auth with the key as the username and a blank password. The older Track API uses a Site ID plus API Key pair, which is not the value Prevenue expects here.

After you save the destination, Prevenue shows a Connected badge next to the saved key field but keeps the password input empty. This is intentional: saved secrets are encrypted and not displayed again. On future edits, leave the field blank to keep the saved key, or enter a new key only when you want to rotate it.

Find the Service Account Token

The Service Account Token is optional for base sync and required for audience automation. Add it when Prevenue should create managed Customer.io audiences, reconcile managed static membership, or manage manual segment membership.

1. In Customer.io, open Account Settings > Manage API Credentials > Service Accounts.
2. Make sure you have permission to manage Service Accounts.
3. Create a Service Account token for the workspace you are connecting to Prevenue, or copy an existing Prevenue-specific token.
4. Store the token somewhere safe before leaving Customer.io.
5. Paste it into Prevenue as Service Account Token.
6. Add the matching Workspace URL or ID for the same workspace.

Customer.io Service Account tokens are exchanged for short-lived bearer tokens before Prevenue calls workspace API endpoints such as /v1/environments/{environment_id}/segments. Prevenue uses this token only for managed audiences and saved manual segment actions shown in the Customer.io settings panel.

After a Service Account Token is saved, Prevenue shows it as Connected and leaves the input blank for safety. Leave it blank to keep the saved key. If you are correcting the Region or Workspace URL or ID, paste the matching Service Account Token again so Prevenue does not keep an older saved token.

Find the Workspace URL or ID

Customer.io's workspace-scoped APIs use environment_id to mean the target workspace. In Customer.io's API schema, this parameter is the workspace/environment ID. Prevenue accepts either that numeric ID or a Customer.io workspace URL containing /workspaces/{id}.

Use the Workspace URL or ID that belongs to the same workspace as the Service Account Token. It is not your Account ID, Pipelines API Key, Site ID, source ID, segment ID, campaign ID, broadcast ID, or message ID.

Fastest UI check:

1. Open Customer.io and switch into the workspace you are connecting to Prevenue.
2. Open any workspace page, such as Workspace Settings, People, or Segments.
3. Look at the browser URL.
4. If the URL contains /workspaces/12345/..., copy the URL or 12345 into Prevenue as the Workspace URL or ID.
5. If the URL only shows /workspaces/last/..., use the CLI/API fallback below.

Customer.io CLI/API fallback:

cio auth status --jq '{account_id, region}'

Copy the account_id, then list the workspaces/environments in that account:

cio api /v1/accounts/{account_id}/environments \
  --params '{"account_id":"<account_id>"}' \
  --jq '.environments[] | {id, name}'

Use the id beside the workspace name you are connecting to Prevenue.

The CLI uses a Customer.io service account token to read account metadata. That is the same class of credential Prevenue expects in the Service Account Token field, but it does not belong in the Pipelines API Key field.

You can skip this field when you only want base Pipelines sync. If you add a Service Account Token without a Workspace URL or ID, Prevenue keeps data sync working but locks managed audience and manual segment actions.

Credentials not to use

Setup steps

1. Open Settings > Integrations > Customer.io in Prevenue.
2. Choose the Customer.io region. For EU Customer.io accounts, choose EU; otherwise choose US.
3. Paste the Pipelines API Key.
4. Save the destination.
5. Send a Customer.io test event.
6. Confirm the destination status changes to ready or connected.
7. Optional: open the Audiences tab and add Service Account Token plus Workspace URL or ID to unlock managed audiences and manual segment actions.
8. Open activity if the test fails or needs attention.

Managed audiences

Managed audiences let Prevenue create and maintain Customer.io segments for the lifecycle motions Prevenue detects. Open the Customer.io Audiences tab in Prevenue to activate presets, choose dynamic or managed static mode, repair sync, and open the Customer.io segment link.

The presets are grouped by the Customer.io Journey action a lifecycle team would usually take, not one segment for every raw signal type. Each row's Setup drawer shows the exact signal types, minimum priority, active statuses, freshness window, contact targeting, and exit rules that control entry.

Signal category is the lifecycle motion Prevenue assigns when it generates the signal. It does not mean the signal was generated by a Customer.io automation. Funnel or Signal delivery can sync the state later, but managed audience entry comes from Prevenue's saved signal state. For example, Upgrade ready accepts either upgrade_ready from the regular account signal rules or event_healthy_momentum_growth from Event KPI and product-event analysis.

The default audiences are:

Prevenue can create these as dynamic trait-based segments or managed static segments:

• Auto creates dynamic trait-based segments when Customer.io person traits are the best fit.
• Dynamic traits creates Customer.io data-driven segments from Prevenue's current managed-audience traits.
• Managed static creates a Customer.io manual segment and reconciles exact add/remove membership from Prevenue.

For most teams, start with Auto. Use Managed static when you need exact membership removal, audit rows, or static manual segments for existing Journey setup.

Managed audiences require Service Account Token + Workspace URL or ID for segment creation, status checks, and managed static membership reconciliation. Current state traits still flow through Pipelines on identify and group calls whenever Customer.io delivery is routed.

Managed audience traits

Prevenue writes these traits to Customer.io when a signal belongs to a managed audience:

Account intelligence fields continue to be sent beside these traits. For an upgrade-ready signal, realistic branching fields include prevenue_signal_type = upgrade_ready, prevenue_signal_category = grow, prevenue_signal_priority = high, prevenue_score_key = expansion_readiness, prevenue_score_label = Expansion ready, prevenue_score = 91, and prevenue_confidence_label = High.

Example Customer.io trait payload:

{
  "email": "alex.rivera@example.com",
  "first_name": "Alex",
  "last_name": "Rivera",
  "name": "Alex Rivera",
  "role": "buyer",
  "title": "VP Revenue",
  "prevenue_active_audience_key": "upgrade_ready",
  "prevenue_active_signal_type": "upgrade_ready",
  "prevenue_active_signal_category": "grow",
  "prevenue_active_signal_priority": "high",
  "prevenue_active_signal_status": "new",
  "prevenue_active_signal_id": "signal_123",
  "prevenue_active_signal_at": "2026-06-29T15:30:00.000Z",
  "prevenue_active_until": "2026-07-29T15:30:00.000Z",
  "prevenue_conflict_group": "lifecycle_motion",
  "prevenue_active_ttl_days": 30,
  "prevenue_active_ttl_source": "motion_default",
  "prevenue_active_recommended_action": "Send a sales-assist follow-up to Alex Rivera.",
  "prevenue_score_key": "expansion_readiness",
  "prevenue_score_label": "Expansion ready",
  "prevenue_score": 91,
  "prevenue_confidence_label": "High"
}

Conflict and removal behavior

Prevenue uses conservative conflict handling for the default lifecycle audiences:

• Active save signals suppress grow and convert audiences.
• Grow and convert signals can replace each other by priority and recency when they are in the same conflict group.
• A signal rule's stale_after_days overrides the managed audience TTL when present.
• Signals with resolved, suppressed, stale, disabled, won, or lost status remove active membership.
• won and lost are cleanup states only in v1. Prevenue does not create outcome audiences for them.

Primary contact resolution is signal person -> account primary email -> skipped missing identity. Prevenue does not automatically add every known account contact to a managed static segment in v1.

Customer.io does not expose a full manual segment member-list API for Prevenue to diff against, so managed static reconciliation is desired-state based. Prevenue records each intended add/remove, retries safe failures, re-checks the latest signal state before stale retries, and never calls a destructive "clear segment" operation.

Prevenue can create and inspect managed audience segments, but it does not create Customer.io Journeys, campaigns, broadcasts, or message content. Your lifecycle team maps Customer.io Journeys to the managed audience segments and traits.

Manual static segment actions

Manual static segment mappings are data-only activation actions for teams that already have their own Customer.io segment structure. A mapping can add or remove a known Customer.io person from a selected manual segment when signal criteria match.

Each mapping requires:

• Service Account Token and Workspace URL or ID.
• A Customer.io manual segment ID.
• Add or remove action.
• Signal category and minimum priority.
• Optional signal type and minimum confidence.
• A known person identifier, either email or user/customer ID.

In Customer.io, create the segment under Segments > Create Segment > Manual. Use the ID for that manual segment in Prevenue. People must already be identified in Customer.io before Customer.io will add them to a manual segment.

Manual mappings are advanced and backward-compatible with earlier Customer.io setup. New lifecycle setup should usually use managed audiences first. Missing credentials, Workspace URL or ID, segment ID, or person identity creates a skipped activity row instead of an API call.

Rollout and rollback

Managed audiences are visible in the Customer.io Audiences tab. Prevenue does not create Customer.io managed audience segments until an admin activates a preset.

Recommended rollout:

1. Activate one managed audience, usually Prevenue - Upgrade ready.
2. Confirm status/count and open the Customer.io segment link.
3. Map one test Journey to the segment or active traits.
4. Send a Prevenue Customer.io setup test and then route a real test signal.
5. Review Prevenue activity for create, state sync, status/count, and membership rows before enabling more audiences.

Rollback:

1. Disable the managed audience in Prevenue to stop managed static reconciliation and queue static removals where Prevenue owns membership.
2. Pause the Customer.io Journey or remove the segment entry condition for immediate campaign stop.
3. Keep the Customer.io segment for audit, or archive/delete it manually in Customer.io if your lifecycle team no longer needs it.

Existing manual segment mappings are not changed when you create, repair, or disable managed audiences.

Not in v1

Prevenue does not create Customer.io Journeys, campaigns, broadcasts, or message content in v1. Create the Journey in Customer.io and use Prevenue-managed audience segments or traits as entry and branching criteria.

API-triggered broadcasts are not included in v1. Broadcasts are usually audience-wide or campaign-oriented, while this integration is scoped to explicit account/person signal actions.

Outcome audiences for won and lost are not included in v1. Those statuses remove accounts or people from active managed audiences, but Prevenue does not claim attribution or enroll them into a separate outcome segment.

Customer.io Reporting Webhooks are deferred. They can be useful for downstream delivery analytics, but v1 focuses on outbound Prevenue sync, managed audiences, manual static segment membership, and readable Prevenue activity logs.

Activity and idempotency

Prevenue writes Customer.io delivery rows for:

• Setup tests.
• Signal sync.
• Identity skips.
• Managed audience creation, status checks, desired-state reconciliation, and membership actions.
• Static segment actions.
• External API failures.

Activity payload summaries avoid raw credentials and provider response bodies. Signal sync, managed audience membership actions, and manual segment actions use idempotency keys so repeated signal processing does not duplicate Customer.io data updates.

Troubleshooting

Related articles

• Integrations
• API and Webhooks
• Event Mapping and Signal Readiness
• Signals
• Customer.io API credential docs
• Customer.io Pipelines vs Track API docs
• Customer.io account region docs