Overview

Use the Management API to create an integration campaign and its component hierarchy directly in Extole. This workflow is for installers, solution engineers, and the operational services that build an integration for a client account rather than shipping it as a packaged bundle in Extole's integration library.

An API-created integration is still a component-based integration, so it must follow the same rules as a packaged one:

• Reusable component types, rather than one-off controllers written for a single partner.
• Typed sockets — the named attachment points on a component that accept only components of a declared type, such as a views socket that holds view components. Create the Integration Campaign and Component Model describes each socket this build uses.
• Business-event templates — maintained components that produce a canonical Extole event such as converted or shipped, duplicated into your campaign instead of rebuilt. Integration Categories explains how a partner's own event names map onto them.
• v10 component types, the current generation of the integration component model. Type names carry the generation as a suffix, as in integration-v10.1 and config-view-v10.0.
• The same naming conventions and validation rules a packaged integration passes before it is published.

Decide Whether This Is an Install or a Client-Local Build

Creating an integration-shaped campaign and installing a registered integration are different outcomes.
The distinction matters whenever the requester expects the result on the My Extole
Integrations page.

The Integrations page selects built components by the tag internal:type:integration. Among those, it
treats a component as this client's installed integration when the component's source client is this
client, and as an available type to install when the source client is Extole. Two further conditions
decide whether a client-owned component shows up at all:

• Root components are excluded. The integration component must be a child of the campaign root,
  never the root component itself.
• Without internal:self-managed the entry renders as unavailable rather than installed.

The tags that decide visibility therefore sit on the non-root integration component. A build that
follows the component model below is visible; one that puts the integration tags only on the campaign,
or only on the root component, is not.

internal:integration-component-name:<component-name> is a separate, older convention. Library bundles
carry it on the integration campaign so an installed copy can be traced back to the component it came
from, and this guide keeps it for parity with those bundles. The Integrations page does not read it, so
setting it does not make a build appear and omitting it does not hide one. Do not reach for it to fix a
build that is missing from the page — check the component's tags, its owner, and whether it is the root.

Building the tree in one account does not register a new partner for anyone else. When the request is
for a new installable partner that every client can see, build and validate the shape in the
development account first, then publish the reusable component to the Extole-owned library, and say
plainly that the account-local build is not yet an installable integration.

Examples in this guide use a generic partner named example. Substitute the real partner name, event names, and field names from that partner's own documentation.

Where a partner-specific page exists in this documentation set, read it first: it carries the wire contract for that platform — event names, payload fields, and status mapping — while this guide carries the build sequence that applies to every platform. Partner pages are published under the partner's name as the page slug, so retrieve the page directly by that slug rather than relying on a keyword search to surface it.

Choose the Integration Category First

Place the platform in a category before creating anything. Integration Categories describes what each category contains and how to recognize it; this guide carries the API sequence that builds it. Pick the path from discovery, not from habit.

Before creating anything, query the duplicatable listing for integration components and look for one whose name matches the partner. Match on the component name, not on a fixed type version: the integration type is revised over time, so a source may be typed integration-v10.0, integration-v10.1, or a later revision, and a query pinned to one revision reports a maintained partner as missing. Prefer that name match over building from custom_integration. Rebuilding a maintained partner from the custom template produces a campaign that looks related and does none of the partner's webhook or credential work.

A request that adds inbound scope to a maintained outbound partner uses both paths: install the library source first, then add business events to the installed campaign using the inbound sequence.

Where the Rest of This Guide Lives

This page carries what every build path shares. The sequences themselves are separate pages, each short
enough to be retrieved whole:

Read the page for the path you are on rather than working from this one alone. A build that stops after
the campaign and the integration component has created the container and none of the integration.

Creation Contract

Follow these rules whenever you create or change an integration through the API, whether you are working by hand or driving the calls from a service:

1. Confirm the client, environment, partner platform and version, inbound and outbound scope, event contract, credential owner, and publication approval before making changes.
2. Read the partner's current documentation and verify version-specific event hooks. Do not infer hook names or payload shapes from another platform.
3. Inspect the target client before creating resources. Reuse an active integration when its campaign and component identity match the request, extend it, and report that. Archived campaigns are not candidates for reuse: they receive no events and hold no program label against a new campaign, so their presence is not a reason to restore one, to pick a different label, or to ask the requester which path to take instead of building what they asked for.
4. Discover first whether a maintained integration source already exists for the partner, matching on component name across every current integration-v10.x type rather than on one pinned revision. When it does, install that source by duplicating it into a new campaign, then reshape it to the partner page's finished tree and webhook set before configuring credentials. Build from the custom integration template only when no maintained partner integration exists. Do not record library component identifiers in documentation or stored instructions.
5. Treat the calls that complete a reshape — creating a component type, deleting an unused library child, publishing, and creating a webhook — as part of the create instruction rather than as follow-up work for someone else. When one is refused because it requires a higher permission level, raise it and continue; a permission that is available but not currently in effect is not a missing authorization. Stopping after a raw library install leaves the requester with an integration the partner page does not describe.
6. Use campaign-version-scoped mutation endpoints. Refresh the latest campaign version after every mutation.
7. Use reusable business-event, rule, and data components. Do not create a custom controller when a reusable template implements the behavior.
8. Keep partner input event names distinct from canonical Extole business event names.
9. Map every persisted field explicitly, in the same run that creates the business events. Assign key types based on field semantics, not field spelling. A business event with an empty data socket captures nothing and is not a finished event.
10. Add a views socket and at least one configuration view. The view must expose the settings required to complete partner setup.
11. Create reward suppliers, client keys, or webhooks only when an approved outbound flow uses them. A reward fulfillment partner is such a flow: its suppliers, REWARD webhooks, and credential setting are the integration, not extras added to an inbound build.
12. Build and inspect the complete campaign before publishing. Test every inbound event and every configured outbound path.
13. Keep a resource ledger containing campaign, component, external resource, and test identifiers. Use it for verification and cleanup.
14. Never put access tokens, secrets, or private client values in documentation, component descriptions, logs, or example payloads.
15. Report partial results as incomplete. Do not describe a draft, disabled webhook, placeholder URL, or unverified event as production-ready.

Resolve the Inputs

An integration build needs the values below, but almost none of them are things to request from whoever asked for the integration. The partner's name is the input that must be supplied, because it selects the partner page; from there the category, the wire contract, and the finished shape are all readable. Work down this table resolving each value from its source, and treat a question to the requester as the last resort it is:

Only three kinds of value genuinely have no source you can read: a partner-side secret, an account identifier issued by the partner, and an artwork file. Build everything that does not depend on them, then name exactly those in your closing report. A build that stops at the start to collect the whole table has produced nothing, and the answers would have been the same ones the pages already give.

Management calls and event submission share one host. Every example in this guide reads it from this variable:

EXTOLE_API_HOST=https://api.extole.io

Campaigns, components, webhooks, and reward suppliers are Management API calls; event submission is a Server to Extole call. Both go to api.extole.io, as described in REST APIs. Send Platform Events to Extole covers the sending side in full.

One host does not mean one credential. Use separate access tokens for integration management and event submission: the partner application receives only the token that can submit events, never the one that can manage campaigns and components.

Use Roll-Forward Campaign Versions

Campaign mutations create a new version. A version used by one successful request is stale for the next request.

Refresh the version before every version-scoped 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'
)

Use the singular path segment /version/{version}:

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

Do not use /versions/. If the API returns stale_version or concurrent_update, retrieve the campaign again, reconcile the latest state, and retry only the intended mutation.

Discover Reusable Components

Find templates at execution time through the duplicatable-components endpoint. This endpoint returns components that the current client can duplicate, including components made 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"

After the target component and socket exist, add target_component_id and target_setting_name to return only components compatible with that socket. Do not use the deprecated target_socket_name parameter. Narrowing this way is the reliable form of the query, because a widely used source such as input_event also appears once for every campaign that already installed a copy of it.

Use these reusable sources:

Validate each candidate's type before duplicating it, and prefer the v10 type when a legacy version of the same name is also returned.

Several results with the same name and the same v10 type are copies of one maintained source, one per campaign that installed it, not a choice between different behaviors. Narrow by the target socket and duplicate the maintained source; that is not the ambiguity worth stopping for. Stop when discovery returns no published match of the required type, or when two genuinely different components could satisfy the request and choosing wrongly would change behavior.

Record the Result

The creation response must include:

• Environment and client.
• Campaign identifier, current version, state, and program label.
• Root and model component identifiers.
• Canonical business events and partner trigger names.
• Field mappings and key types.
• View components and displayed settings.
• External resources created, or an explicit statement that none were required.
• Programs whose business events were replaced or added to, or an explicit statement that the integration is not yet connected to a program.
• Test event identifiers and verification results.
• Documentation URL.
• Remaining manual partner steps.

Do not claim the integration is complete while partner-side installation, credentials, status mapping, or end-to-end tests remain outstanding.