Skip to Content
API ReferenceCampaign Variables

Campaign Variables

This reference covers runtime business variables used inside ResultFly campaign execution.

Campaign variables are not the same thing as CDP profiles, channels, or event history. They are runtime values used by campaign logic.

1. Scopes

ResultFly supports two business scopes:

  • user_global
  • user_campaign

These are exposed in runtime state as:

  • state.user_global.*
  • state.user_campaign.*

2. Authentication

  • Variable definition endpoints require server-side or administrative credentials.
  • Runtime read and mutation endpoints require a user-context JWT.

See Authentication.

3. Contract Boundary

Campaign variables are managed through two technical surfaces:

  • an administrative/configuration surface for declaring variables
  • a runtime surface for reading and mutating declared values for the authenticated participant

The exact route names follow the deployed admin and runtime APIs. This page documents the data model and the expected behavior, not a separate public REST namespace for variables.

4. Variable Definitions

4.1 Organization-level user variables

Organization-level user variables belong to user_global.

Example definition shape:

{
  "name": "loyalty_points",
  "type": "number",
  "defaultValue": 0,
  "description": "Lifetime balance used by runtime logic"
}

4.2 Campaign-level variables

Campaign-level variables belong to user_campaign.

They are managed through campaign configuration.

Example payload fragment:

{
  "variables": {
    "user_campaign": [
      {
        "name": "tasks_completed",
        "type": "number",
        "defaultValue": 0,
        "description": "Progress inside this campaign"
      }
    ]
  }
}

5. Runtime Read

Runtime read operations return the current declared variable values for the authenticated participant.

Example shape:

{
  "state": {
    "user_global": {
      "loyalty_points": 1200
    },
    "user_campaign": {
      "tasks_completed": 2
    }
  }
}

6. Runtime Mutation

Runtime mutation operations apply changes to declared variables for the authenticated participant.

Expected mutation shape:

FieldTypeRequiredDescription
opsarray✅Mutation operations.
ops[].pathstring✅Variable path such as state.user_campaign.tasks_completed.
ops[].openum✅set, inc, dec, assign, increment, decrement.
ops[].valuescalar✅Value to apply.
mutationIdstring❌Idempotency key for retry-safe mutations.

Example request:

{
  "ops": [
    {
      "path": "state.user_campaign.tasks_completed",
      "op": "inc",
      "value": 1
    }
  ],
  "mutationId": "mut_001"
}

7. Important Limits

  • Only declared variables may be used.
  • System state is not writable through this API.
  • These endpoints are for campaign runtime, not for canonical customer-data ingestion.

If the value should become part of segmentation, profile history, channel state, or audience export, model it in the CDP rather than only in runtime variables.

Event Ingestion