Overview

A packaged integration is a campaign whose component tree connects Extole to an outside platform, assembled from reusable component types so the same build can be installed and configured in any account. The Management API builds that campaign and its components directly in a client account. The model is the same whether or not the finished build is published to Extole’s integration library:

Reusable component types, not one-off controllers.
Typed sockets — attachment points that accept only components of a declared type, such as a views socket holding view components.
Business-event templates — maintained components that produce a canonical Extole event such as converted or shipped.
v10 component types, named with the generation as a suffix: integration-v10.1, config-view-v10.0.
The naming conventions and validation rules the integration passes before publication.

Examples use a generic partner named example. Substitute the real partner name, event names, and field names.

Who Packages an Integration

Packaging is platform engineering on a reusable artifact — a partner connector meant to be installed repeatedly and maintained over time. It is not a step in launching a program, and most clients never do it. Extole solutions engineers, partner engineering teams, and clients building a connector for a platform Extole does not yet maintain are the audience for this guide. If you are connecting your own systems to Extole, one of these is your path instead:

You want	Go to
To connect your site, app, or servers and launch a program	Integrating with Extole — the JavaScript SDK, REST APIs, and mobile SDKs
To connect a platform Extole already maintains	Install it from the My Extole Integrations page; there is nothing to build
To send your own platform’s events server-side	Send Platform Events to Extole
To send records as CSV or SFTP files	The File Integration extension

Even when packaging is your job, confirm Extole does not already maintain a source for the partner before you build anything — When You Would Build One starts there.

Build with Extole AI Tools

The recommended path is to run the build through the Extole MCP server from an agentic coding tool — Claude Code, Cursor, or Codex — with the Extole CLI alongside it. Point the tool at this guide and the partner’s page, and describe the integration you need. The build suits an agent better than it suits a person:

It is dozens of component duplications in a required order, each needing a fresh campaign version, and one stale value rejects the call.
Library components resolve by name at build time, so every duplication starts with a lookup whose result is used once and never stored.
Verification uses the same tool surface as the build: read the component tree back, send a test event, read the resulting steps.
Changes execute under your own Extole permissions and are attributed to you in the change log, exactly as they are through My Extole or the API.

The curl examples throughout this guide are the underlying contract. Read them to understand what a tool did, to check a finished build, or to work through the sequence by hand.

When You Would Build One

You want	Category	Start at
A client’s commerce, banking, or subscription platform to send purchases, shipments, or account activity into Extole	Inbound	Map Inbound Partner Events
Extole activity to reach a marketing automation, messaging, analytics, or customer data platform	Outbound	Build an Outbound Library Integration
Extole to order gift cards, prepaid cards, points, or payouts when a participant earns a reward	Reward fulfillment	Build a Reward Fulfillment Integration
A partner’s own webhook, whose payload you do not control, to produce Extole events	Inbound with a prehandler	Normalize Inbound Events with a Prehandler
A platform to decide who is eligible and send that membership to Extole, rather than reporting events	Inbound, as audience membership	Receive Audience Membership from a Partner
To inspect, configure, or test the component model in a development account	Any	Create the Integration Campaign and Component Model

Integration Categories describes what each category contains. A partner that both sends outcomes and receives rewards uses two paths: build the inbound half first, then add the outbound resources. Adding inbound scope to a maintained outbound partner works the same way — install the library source, then add the inbound half to the installed campaign, business events for a partner that reports activity or an audience and credential for one that sends eligibility. Check the finished integration against every category the request matched. Check for a maintained library source before building anything. Query the duplicatable listing for an integration component whose name matches the partner, not a fixed type version — a source may be typed integration-v10.0, integration-v10.1, or later, and a query pinned to one revision reports a maintained partner as missing. Rebuilding a maintained partner from custom_integration produces a campaign that does none of the partner’s webhook or credential work. When this documentation set has a page for your partner, read it first. It carries that platform’s wire contract — event names, payload fields, status mapping. Partner pages use the partner’s name as the page slug.

Client-Local Build or Registered Integration

Building the tree in one account does not register the partner for anyone else.

Outcome	What to do
An integration this client uses	Duplicate the library source, or build the campaign and component tree.
An integration every client can find and install	Build and validate in a development account, then publish the reusable component to the Extole-owned library.

The My Extole Integrations page lists components tagged internal:type:integration. It treats one as installed when its source client is this client, and as available to install when the source client is Extole. Two conditions decide whether a client-owned component appears at all:

The integration component must be a child of the campaign root. Root components are excluded.
Without internal:self-managed the entry renders as unavailable.

internal:integration-component-name:<component-name> is an older convention that library bundles carry for traceability. The Integrations page does not read it, so it neither reveals nor hides a build. When an integration is missing from the page, check the component’s tags, its owner, and whether it is the root.

Before You Start

Source	Values
The partner page, then the partner’s developer documentation	Platform and version, category, event names and payload fields, identity and deduplication fields, status mapping, the settings the integration exposes, and any outbound destination, authentication, and retry contract
Derived from the partner name	Campaign name, a stable lowercase component name, and a unique program label
Your Extole account	A server-side access token from the Security Center authorized to manage campaigns and components and to read people, and the client that token authenticates to
Nowhere — request these	The partner’s API secret, any account identifier the partner issues, and the logo artwork

Confirm the target client before the first write. A token pointed at the wrong account builds a live integration there. The last row does not block the build. Build everything that does not depend on those three values and track them as outstanding.

One Host, Two Access Tokens

Management calls and event submission both go to api.extole.io. Examples read it from EXTOLE_API_HOST:

EXTOLE_API_HOST=https://api.extole.io

Use separate access tokens for the two. The partner application receives only the token that can submit events, never the one that can manage campaigns and components.

How to Build

Work through the pages in order. Each build sequence is a page of its own:

Page	Covers	Needed for
Create the Integration Campaign and Component Model	The campaign, root, and integration component; display metadata and logo; typed sockets and the configuration view	Every path
Add the Activity and Event Views	The report-runner and event-stream views, the report runner and event stream behind them, and the republish each attachment needs	Every path
Map Inbound Partner Events	Business events, input event rules, and event data	Inbound
Normalize Inbound Events with a Prehandler	Reshaping a partner’s own webhook at ingest	Inbound, when the partner defines the payload
Receive Audience Membership from a Partner	The audience, the credential the partner authenticates with, and the setup instructions naming the membership endpoints	Inbound, when the partner sends eligibility rather than events
Build an Outbound Library Integration	Installing a maintained source, reshaping it, and attaching webhooks and a credential	Outbound
Build a Reward Fulfillment Integration	Supplier type, support campaign, supplier templates, and `REWARD` webhooks	Reward fulfillment
Validate and Publish an Integration	Gating outbound resources, the validation checklist, and connecting the integration to a program	Every path

A campaign and an integration component alone are the container. The events, views, and webhooks are the integration.

Refresh the Campaign Version Between Mutations

Every campaign mutation creates a new version, and version-scoped endpoints reject a stale one. Read the version immediately before each mutation:

CAMPAIGN_VERSION=$(
  curl --silent --show-error --fail-with-body \
    "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID" \
    --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" |
  jq --raw-output '.version'
)

The path segment is singular — /version/{version}, not /versions/:

/v2/campaigns/{campaign_id}/version/{version}/components

On stale_version or concurrent_update, retrieve the campaign, reconcile, and retry only the intended mutation.

Find Reusable Components

GET /v1/components/duplicatable returns the components this client can duplicate, including those available through subscriptions and grants:

curl --get "$EXTOLE_API_HOST/v1/components/duplicatable" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --data-urlencode "name=template_transacted_business_event" \
  --data-urlencode "version_state=PUBLISHED" \
  --data-urlencode "having_any_types=business-event-v10.0" \
  --data-urlencode "show_all=true"

Component	Program label	Purpose
`template_transacted_business_event`	`business-events`	Revenue or transaction outcome
`template_tracked_business_event`	`business-events`	Non-revenue lifecycle milestone
`input_event`	`rules`	Matches one or more partner input event names
`business_event_data`	`business-events`	Captures one mapped field
`event_id`	`business-events`	Captures the Extole event identifier

Once the target component and socket exist, add target_component_id and target_setting_name to return only socket-compatible components. target_socket_name is deprecated. Narrowing this way matters because a widely used source such as input_event appears once for every campaign that installed a copy of it — those duplicates are copies of one maintained source, not alternative behaviors. Check each candidate’s type before duplicating, and prefer v10 when a legacy version shares the name.

Constraints

These hold on every path:

Resolve library components by name at build time. Stored identifiers go stale without failing loudly.
Use the reusable business-event, rule, and data components. Write a custom controller only where no template implements the behavior.
Carry all three baseline views — configuration, report-runner, and event-stream. The category decides what the report counts and what the feed filters to, not whether the tabs exist. Reward fulfillment adds a fourth, a reward-suppliers configuration view.
Create reward suppliers, client keys, and webhooks only for an outbound flow the integration has. An inbound integration needs none.
Keep partner event names and canonical Extole names separate. The trigger rule carries the wire name; the business event carries converted, shipped, or another canonical name. Renaming a business event to match a partner breaks every program and report reading the canonical name.
Map every field you persist, in the same pass that creates the business events. A business event with an empty data socket cannot deduplicate, attribute, reward, or report.
Assign key types by meaning, not spelling. A partner field named customer_id may hold the partner’s own identifier rather than an Extole person key.
Keep secrets in a webhook client key or protected setting — never in component descriptions, logs, or example payloads.

Reusing an active integration whose campaign and component identity already match is preferable to building a second one. Archived campaigns are not candidates: they receive no events, and an archived campaign holds no program label against a new one, so its label is free to reuse.

How to Test

Test every inbound event and every configured outbound path before you call the integration live. Inbound. Send a synchronous event to POST /v6/events with the current program label in data.labels, then read the step it produced:

curl --get "$EXTOLE_API_HOST/v5/persons/$PERSON_ID/steps" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --data-urlencode "campaign_ids=$CAMPAIGN_ID" \
  --data-urlencode "names=converted"

Confirm the step carries the canonical event name, that the transaction identifier and value match the source record, that person keys resolve, and that resending the same source identifier produces a duplicate outcome rather than a second conversion. Repeat for every event the integration accepts. Send Platform Events to Extole covers the sending side and what to check when Extole accepts an event but no business event appears. Outbound. Trigger the Extole event the integration forwards and confirm the webhook fired against the partner endpoint. The component tree. Read the campaign and its built components back. Confirm every typed child carries its type, each webhook exists with its tags and resolved URL, and each WEBHOOK_ID setting resolves to a webhook identifier. A successful publish validates the model, not the behavior. Prehandler scripts and a data component’s valueExpression are stored without ever being executed, so only a real payload proves they run. Validate and Publish an Integration covers the full gate. The integration is not live while the campaign is in draft, a webhook is disabled, a URL is a placeholder, or an event is untested.

What to Record

Keep these identifiers as you build, for verification and for cleaning up test data:

Client and environment.
Campaign identifier, version, state, and program label.
Root and integration component identifiers.
Canonical business events and the partner trigger names that reach them.
Field mappings and key types.
View components, and the report runner and event stream each resolves to.
External resources created, or confirmation the category needed none.
Programs whose business events changed, or confirmation the integration is not yet connected to one.
Test event identifiers and results.
Partner-side steps that remain.

Integration Overview

Extole AI Tools

Platform Integrations

Partners

Building Packaged Integrations

Solutions

Operational Tasks

Troubleshooting

Build a Packaged Integration with the Management API

Overview

Who Packages an Integration

Build with Extole AI Tools

When You Would Build One

Client-Local Build or Registered Integration

Before You Start

One Host, Two Access Tokens

How to Build

Refresh the Campaign Version Between Mutations

Find Reusable Components

Constraints

How to Test

What to Record

​Overview

​Who Packages an Integration

​Build with Extole AI Tools

​When You Would Build One

​Client-Local Build or Registered Integration

​Before You Start

​One Host, Two Access Tokens

​How to Build

​Refresh the Campaign Version Between Mutations

​Find Reusable Components

​Constraints

​How to Test

​What to Record

​Related Documentation

Overview

Who Packages an Integration

Build with Extole AI Tools

When You Would Build One

Client-Local Build or Registered Integration

Before You Start

One Host, Two Access Tokens

How to Build

Refresh the Campaign Version Between Mutations

Find Reusable Components

Constraints

How to Test

What to Record

Related Documentation