Store a campaign integration reference — Campaigns

Stores or replaces the link keyed by organization, workspace, campaign, applicationId and purpose. It does not replace every campaign integration.

Store a campaign integration reference

Stores or replaces the link keyed by organization, workspace, campaign, applicationId and purpose. It does not replace every campaign integration.

Outcome and boundaries

Stores or replaces the link keyed by organization, workspace, campaign, applicationId and purpose. It does not replace every campaign integration.

Stores application/resource strings and metadata only: no external lookup, provider provisioning, entitlement, consent or access grant occurs.

Before you start

Confirm the intended environment and current credential organization using whoami; discover the exact application/action before any call.
Required application permission: app_topolo_campaigns.campaigns:write. Catalog discoverability is not permission to execute.
Discover an authorized canonical workspace and bind resourceType workspace/resourceId separately from action input.
All worked cases in this guide are hypothetical source-reviewed illustrations; no business action, live fixture, customer data or provider request was executed.
Canonical workspace minimum access is admin in addition to the application permission. After grant verification, the first request may create an app-local identity/recipient mirror even before the later app-permission check; this is not campaign-domain completion.

Discover the intended identifiers

Read campaigns.get and integrations.list; discover the target application and resource through that application’s published catalog before storing its exact identity.

Action: app_topolo_campaigns.integrations.upsert · PUT /api/campaigns/{id}/integrations.

Input fields

Field	Required	Meaning and validation
`id`	Yes	Campaign identifier from campaigns[].id; scoped to the selected organization/workspace. It is not a batch/code/placement id. string; minLength=1
`applicationId`	Yes	Discovered target application identity stored as a string. The upsert does not validate or authorize that other app. string; minLength=1
`resourceType`	Yes	Published resource type of the target application; storing it does not bind a service credential. string; minLength=1
`resourceId`	Yes	Discovered identifier within that target application and authorized context; no remote lookup or access grant is performed here. string; minLength=1
`purpose`	Yes	Declared relationship category and part of the upsert key. It is not a permission or an instruction to provision another app. string; enum=["qr_series", "landing_site", "claim_form", "crm_workspace", "chat_workspace", "chat_channel", "calendar_event_type", "notification_event"]
`metadata`	No	Stored JSON object. It is not an instruction, access grant or evidence of a provider outcome; avoid credentials or sensitive customer data. object

Safe call sequence

Write the reviewed input to payload.json; fixture identifiers below are unusable examples. Validate before planning, bind the discovered resource separately, and execute only within actual authority.

topolo actions validate app_topolo_campaigns.integrations.upsert --data @payload.json --json
topolo actions plan app_topolo_campaigns.integrations.upsert --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

The published action requires confirmation. Only after the exact mutation is authorized, use that same payload/context with --confirm on plan/call; no operation in this guide has been executed.

Worked cases

Every response below is synthetic and source-reviewed, not captured. HTTP status and body are explained independently; a structurally valid body alone never proves successful execution. Middleware may add a different error envelope.

Store a Quro series reference · HTTP 200

Input:

{
  "id": "campaign_example",
  "applicationId": "app_topolo_quro",
  "resourceType": "qr_series",
  "resourceId": "series_example",
  "purpose": "qr_series"
}

Illustrative response:

{
  "integration": {
    "id": "integration_example",
    "applicationId": "app_topolo_quro",
    "resourceType": "qr_series",
    "resourceId": "series_example",
    "purpose": "qr_series",
    "metadata": {},
    "createdAt": "2026-10-20T00:00:00.000Z",
    "updatedAt": "2026-10-20T00:00:00.000Z"
  }
}

Replace only the same application/purpose link · HTTP 200

Input:

{
  "id": "campaign_example",
  "applicationId": "app_topolo_quro",
  "resourceType": "qr_series",
  "resourceId": "series_example_2",
  "purpose": "qr_series"
}

Illustrative response:

{
  "integration": {
    "id": "integration_example",
    "applicationId": "app_topolo_quro",
    "resourceType": "qr_series",
    "resourceId": "series_example_2",
    "purpose": "qr_series",
    "metadata": {},
    "createdAt": "2026-10-20T00:00:00.000Z",
    "updatedAt": "2026-10-20T00:00:00.000Z"
  }
}

Missing campaign · HTTP 404

Input:

{
  "id": "campaign_absent",
  "applicationId": "app_topolo_quro",
  "resourceType": "qr_series",
  "resourceId": "series_example",
  "purpose": "qr_series"
}

Illustrative response:

{
  "error": "campaign_not_found"
}

Verify the outcome

List integrations and match applicationId, purpose, resourceType and resourceId. Verify external access and provider connectivity separately through their owners.

Refusals and recovery

HTTP 404 campaign_not_found: Correct the named input or retain the authoritative refusal in the same context.
HTTP 400 integration_resource_required: Correct the named input or retain the authoritative refusal in the same context.
HTTP 400 invalid_purpose: Correct the named input or retain the authoritative refusal in the same context.
HTTP 403 forbidden: Raw handler permission refusal. SDKs can normalize it to permission_denied. Keep the same intended resource; do not widen access.
HTTP 403 workspace_forbidden: The canonical workspace grant refused the selected resource. Resolve it with the access owner, not a guessed workspace.

Snapshot the existing tuple and metadata before replacement. A reviewed upsert of that same application/purpose can restore prior fields; no integration deletion action is published and other tuples must remain untouched.

Source and catalog limits

Published REPLACES-the-wiring wording is too broad. The conflict key includes applicationId and purpose; unrelated links survive.

Exact schemas and provenance

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "applicationId": {
      "type": "string",
      "minLength": 1
    },
    "resourceType": {
      "type": "string",
      "minLength": 1
    },
    "resourceId": {
      "type": "string",
      "minLength": 1
    },
    "purpose": {
      "type": "string",
      "enum": [
        "qr_series",
        "landing_site",
        "claim_form",
        "crm_workspace",
        "chat_workspace",
        "chat_channel",
        "calendar_event_type",
        "notification_event"
      ]
    },
    "metadata": {
      "type": "object",
      "properties": {},
      "additionalProperties": {}
    }
  },
  "required": [
    "id",
    "applicationId",
    "resourceType",
    "resourceId",
    "purpose"
  ],
  "additionalProperties": false
}

Output schema:

{
  "type": "object",
  "title": "integrations upsert response",
  "description": "Operation result returned by integrations.upsert.",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "id": {
      "type": "string"
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "title": "integration record",
          "properties": {
            "id": {
              "type": "string",
              "description": "Stable identifier when the integration exposes one."
            }
          },
          "additionalProperties": true
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "result": {
      "type": "object",
      "additionalProperties": true
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "x-topolo-contract-source": "derived-action-metadata",
  "x-topolo-contract-precision": "structural"
}

Reviewed immutable source: TopoloCampaigns@cacbb8b12b4e19a662cf82d03a927aef3c3a35e8, apps/api/src/campaign-orchestration-store.ts. Fresh production catalog was read on 2026-10-20. Its publication metadata is not proof that this source is loaded. Output examples are not widened or rewritten to force schema success; the accompanying validation record classifies exact success, refusal, no-body and structural-schema limits.

List campaign integrations — Campaigns: Lists stored application/resource links for the campaign. It does not call another application, verify a linked resource, grant access or establish provider connectivity. An absent campaign can return an empty list.
Get campaign — Campaigns: Reads one non-deleted campaign in the bound organization and workspace. An absent or differently scoped campaign returns HTTP 404 campaign_not_found.

Local input rejection example

This deliberately invalid input belongs to a pure schema check; it is never a planned or executed request. The closed action input schema must reject the extra field. It has no HTTP status or server response.

{
  "id": "campaign_example",
  "applicationId": "app_topolo_quro",
  "resourceType": "qr_series",
  "resourceId": "series_example",
  "purpose": "qr_series",
  "__unsupported_field": true
}

The hidden companion labels this as ILLUSTRATIVE_LOCAL_SCHEMA_CHECK; its validation representation is not an action output.

Published output validation limits

Current published output qualification: the output schema accepts an empty object, a partial success marker, a partial data object and a refusal body. It therefore establishes only broad structure. Require the documented HTTP/domain result and source-shaped fields; missing fields or a schema-valid error are not success.

These observations come from pure checks of the exact published schema; they are not server responses or production captures.

Store a campaign integration reference — Campaigns

Store a campaign integration reference

Outcome and boundaries

Before you start

Discover the intended identifiers

Input fields

Safe call sequence

Worked cases

Store a Quro series reference · HTTP 200

Replace only the same application/purpose link · HTTP 200

Missing campaign · HTTP 404

Verify the outcome

Refusals and recovery

Source and catalog limits

Exact schemas and provenance

Related actions

Local input rejection example

Published output validation limits