ActiveCampaign tag preferences

Read locally configured tag choices, inspect member tags or apply selected changes using local Wallkit tag IDs. Member reads and writes first synchronize a provider contact using the current member’s stored email.

Task	Operation
Read allowed tag choices	Read allowed tag choices
Read member tags and synchronize contact	Read member tags and synchronize contact
Update selected member tags	Update selected member tags

Example clients and synthetic values follow response conventions.

Member context

Use an existing active member and valid resource with custom token and resource headers. Shared guards reject inactive callers and locked/suspended relationships. See credential transport.

Member ACL permits these operations. ActiveCampaign’s controller does not apply the API namespace’s configured Firebase user-replacement branch; it uses the ordinary resolved session user. Use the existing credential context supplied for this integration.

The local catalog and member-contact operations have different relationship/configuration requirements and effects. Follow the selected operation below.

Returned local tag projection

Every item is a Wallkit tag model matched to the selected resource. No provider contact or contact-tag relationship ID is returned.

Field	Type / presence	Meaning
id	stored integer / null	Local Wallkit tag ID; use as a key in PUT tags.
resource_id	stored integer / null	Owning Wallkit resource ID.
tag_id	stored provider identifier string / null	Provider tag identifier; not the PUT map key.
tag_type	stored string / null	Provider-derived type; no full enum established.
tag	stored string / null	Tag display name.
description	stored string / null	Tag description.
subscriber_count	stored integer / null	Stored provider count, not a live count refreshed by these operations.
allowed_for_users	stored Boolean flag / null; no explicit cast	Controls the local catalog filter; not an enforced write allowlist.
required	stored Boolean flag / null; no explicit cast	Stored preference metadata; this write does not enforce it.
allowed_for_user	conditional, unspecified stored value	Singular compatibility field is selected but not declared by this model; may be omitted. Do not require it or equate it with allowed_for_users.

Do not assume stored fields are converted to another type unless stated. Catalog and member output apply different filters; see each operation. Empty items does not prove the provider has no tags, because provider tags without matching local models are omitted from member results.

Read allowed tag choices

GET /api/v1/integrations/activecampaign/tags

Read local resource tag models whose allowed_for_users flag is truthy. This catalog does not call the provider or synchronize a contact; it is distinct from the member-tag GET.

Before you call

Use the ActiveCampaign member context.

The resource’s ActiveCampaign active setting must be enabled. This local read does not require a member-resource relationship beyond shared caller guards and does not validate provider key/account readiness. Stored local tag models must already exist.

Request

No request body or action-specific query parameters.

Name	Location	Type / requirement	Meaning
resource	header	resource public key; required	Selects existing resource integration.
token	header	authorized member session token; required	Resolved caller identity; the prerequisite role requirements still apply.

Result

HTTP 200 items array with the local tag projection. No pagination or explicit order/cache policy. Empty items is possible; only allowed_for_users models appear.

Example: Build a tag choice

curl "${WALLKIT_API_BASE}/api/v1/integrations/activecampaign/tags" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/activecampaign/tags`, {
  method: "GET", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/activecampaign/tags",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

Synthetic HTTP 200 excerpt:

{
  "items": [
    {
      "id": 1001,
      "resource_id": 2001,
      "tag_id": "tag-example",
      "tag": "Technology",
      "allowed_for_users": true,
      "required": false
    }
  ]
}

This excerpt omits other stored fields. Keep local ID 1001 for PUT; provider tag-example is a different identifier.

Consequential alternate

Synthetic HTTP 200 excerpt:

{
  "items": []
}

No local models pass the catalog filter. This does not certify an empty provider tag catalog.

Recovery

HTTP status	Code / shape	Cause	Next action
403	activecampaign_get_tags_error / Activecampaign is not enabled	Resource active setting is false.	Ask the integration owner to check the selected resource’s existing configuration.
409	activecampaign_get_tags_error / Get tags is failed	Local tag lookup fails inside its wrapper.	Ask the owner to inspect local configured tag records.

Next task

With a member-resource relationship, use read member tags when its contact-sync write is intended.

Read member tags and synchronize contact

GET /api/v1/integrations/activecampaign/user/tags

Before you call

Use the ActiveCampaign member context.

An existing member-resource relationship is required. The resource must have active ActiveCampaign settings, provider key and account name. Email comes from the current member; user_id/email in the body or query do not select a different contact. No explicit contact/tag cache is used.

Request

No request body or action-specific query parameters.

Name	Location	Type / requirement	Meaning
resource	header	resource public key; required	Selects existing resource integration.
token	header	authorized member session token; required	Resolved caller identity; the prerequisite role requirements still apply.

Result

HTTP 200 items array with the local tag projection. Provider tags without matching local models are omitted. Unlike the catalog, this output does not filter allowed_for_users, so it can show locally disallowed models. The GET does not modify local allowed/required settings or grant Wallkit membership.

Example: Read a matched member tag

curl "${WALLKIT_API_BASE}/api/v1/integrations/activecampaign/user/tags" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/activecampaign/user/tags`, {
  method: "GET", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/activecampaign/user/tags",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

Synthetic HTTP 200 excerpt:

{
  "items": [
    {
      "id": 1001,
      "resource_id": 2001,
      "tag_id": "tag-example",
      "tag": "Technology",
      "allowed_for_users": false,
      "required": false
    }
  ]
}

The false allowed_for_users flag can appear here even though that model is omitted from the public choice catalog. The request also synchronized the provider contact.

Consequential alternate

Synthetic HTTP 404 response:

{
  "error": "get_user_tags_error",
  "error_description": "User not exist in current resource",
  "req_guid": "example-request"
}

No member-resource relationship was found. Supplying a different body user_id will not repair this current-member requirement.

Recovery

HTTP status	Code / shape	Cause	Next action
404	get_user_tags_error / User not exist in current resource	Missing current member relationship.	Check intended existing member/resource association.
403	get_user_tags_error / Activecampaign is not enabled	Provider service initialization sees inactive integration.	Ask the owner to check active settings.
409	get_user_tags_error / Empty api key or Empty account name	Required provider configuration absent.	Ask the integration owner to inspect existing settings; do not put provider credentials in the request body.
409	get_user_tags_error / Create or update contact is failed	Contact sync failed or returned unusable contact data.	Inspect provider outcome before repeating this GET write.
409	get_user_tags_error / Get tags list is failed or Get tags is failed	Provider tag read or local matching lookup failed.	Account for earlier contact sync, then inspect the reported stage.

Next task

Use update selected tags with local IDs only when a provider change is intended; it is not a complete replacement of the catalog.

Update selected member tags

PUT /api/v1/integrations/activecampaign/user/tags

Apply selected tag additions/removals to the current member’s provider contact. Map keys are local Wallkit tag IDs. Unknown keys are skipped; omitted tags are untouched. This action does not enforce allowed_for_users or required flags on writes.

Before you call

Use the ActiveCampaign member context.

An existing member-resource relationship and active provider key/account configuration are required. Current stored email identifies the contact; no alternate user_id/email selector. Even if every supplied tag ID is unknown, the request still synchronizes the provider contact.

Request

Send a JSON object.

Name	Location	Type / requirement	Meaning
resource	header	resource public key; required	Selects existing resource integration.
token	header	authorized member session token; required	Resolved caller identity; the prerequisite role requirements still apply.
tags	JSON	nonempty map of local tag ID to flag; required	Values that evaluate to true in a boolean check add a tag; values that evaluate to false remove it. Use JSON Booleans for clarity; nonempty text such as "false" evaluates to true and adds. Unknown/nonmapped local keys are skipped.

Use local id from the catalog, not provider tag_id. Omitting a key does not remove that tag. No separate add/remove list, consent override or membership field is parsed.

Result

HTTP 200 items array with the local tag projection, matching provider contact tags to local resource models with no allowed_for_users filter. No per-key changed/skipped counts or contact IDs are returned.

After synchronous changes Wallkit also attempts the user_update_activecampaign_tags event with selected map and an empty changes array. Queue-send failures can be caught; HTTP success does not establish queue acceptance, delivery, consent or Wallkit membership. A failure constructing the event helper may still occur after provider changes.

Example: Add one tag and remove another

curl -X PUT "${WALLKIT_API_BASE}/api/v1/integrations/activecampaign/user/tags" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-raw '{"tags": {"1001": true, "1002": false}}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/activecampaign/user/tags`, {
  method: "PUT", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN, "Content-Type": "application/json" },
  body: JSON.stringify({"tags": {"1001": true, "1002": false}})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'tags': {'1001': True, '1002': False}}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/activecampaign/user/tags",
    data=json.dumps(body).encode("utf-8"), headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"], "Content-Type": "application/json"}, method="PUT")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

Synthetic HTTP 200 excerpt:

{
  "items": [
    {
      "id": 1001,
      "resource_id": 2001,
      "tag_id": "tag-example",
      "tag": "Technology",
      "allowed_for_users": true,
      "required": false
    }
  ]
}

Assume local IDs 1001 and 1002 already map to provider tags. The returned matched model remains after changes; this excerpt omits other stored fields and is not a per-key receipt.

Consequential alternate

Synthetic HTTP 200 excerpt when no returned provider tag has a matching local model:

{
  "items": []
}

Empty items can follow a contact-sync write, including when all request keys were unknown. It does not prove every requested removal happened or no provider tags remain.

Recovery

HTTP status	Code / shape	Cause	Next action
404	update_user_tag_error / User not exist in current resource	Missing current member relationship.	Check existing selected member/resource association.
409	update_user_tag_error / Body must be json format	No truthy parsed JSON body.	Send a JSON object with Content-Type: application/json.
409	update_user_tag_error / Empty tags list	tags absent/empty; message has a trailing space.	Supply at least one intended local ID/Boolean pair.
403	update_user_tag_error / Activecampaign is not enabled	Provider service initialization sees inactive integration.	Ask owner to inspect the resource configuration.
409	update_user_tag_error / Empty api key or Empty account name	Existing provider configuration incomplete.	Ask integration owner to inspect configuration.
409	update_user_tag_error / Get tags assoc array is failed	Local ID mapping lookup failed.	Check local tag records with the owner.
409	update_user_tag_error / Create or update contact is failed, Create contact tag is failed, Get tags list is failed, Remove contact tag is failed, or Get tags is failed	Corresponding sync/add/read/remove/match stage failed.	Inspect partial provider state before repeating; wrapper messages replace inner provider details.

Next task

Interpret returned models and any failure before updating the preference UI. A subsequent member-tag read also synchronizes contact; it is not a passive recovery probe.

Follow the task guide

Read the 3rd party integration flows for request order, context choices and response decisions.

ActiveCampaign tag preferences

Member context

Returned local tag projection

Read allowed tag choices

Before you call

Request

Result

Example: Build a tag choice

Consequential alternate

Recovery

Next task

Read member tags and synchronize contact

Before you call

Request

Result

Example: Read a matched member tag

Consequential alternate

Recovery

Next task

Update selected member tags

Before you call

Request

Result

Example: Add one tag and remove another

Consequential alternate

Recovery

Next task

Follow the task guide

Full diagram

Search documentation