Archive prospect list

Outcome

Archive a list while retaining its contacts and membership history.

Before you start

• Verify the environment, credential, authorized organization and the published action permission workspace:write.
• Discover an accessible Engage workspace and bind resourceType=workspace and its resourceId separately from action input. Fixture identifiers grant no access.
• Approve the exact mutation and its effects before CLI --confirm or MCP confirm:true. This documentation does not authorize outreach.

Discover the target

• Discover list id through lists.list, then read lists.get in the selected workspace and inspect archivedAt. Retain the current name, description and active membership state before planning.

topolo whoami --json
topolo actions get app_topolo_engage.lists.archive --json
topolo workspaces list topolo-engage --json

Input fields

Validate, plan and execute

Set ENGAGE_WORKSPACE_ID to the identifier of your selected workspace. Prepare payload.json from the current input schema and discovered identifiers. Use the same payload for validation, planning and execution.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions validate app_topolo_engage.lists.archive --data @payload.json --json
topolo actions plan app_topolo_engage.lists.archive --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --confirm --json

Review the plan and obtain approval for the exact effects before executing the unchanged request.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions call app_topolo_engage.lists.archive --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --confirm --json

For MCP, use topolo_get_action, topolo_validate_action, topolo_plan_action and topolo_call_action. Pass the selected resource context separately; confirm:true is required for mutations.

Worked requests and responses

Captured lists.archive · HTTP 200

Action input

{
  "id": "list_1"
}

Actual local response

{
  "list": {
    "id": "list_1",
    "name": "VCs",
    "description": "Seed",
    "memberCount": 0,
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: audience routes > lists > creates, lists, edits and archives a list. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured lists.archive · HTTP 200

Action input

{
  "id": "list_1"
}

Actual local response

{
  "list": {
    "id": "list_1",
    "name": "Gone",
    "description": null,
    "memberCount": 0,
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: audience routes > imports > refuses unusable files, mappings and target lists. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured lists.archive · HTTP 200

Action input

{
  "id": "list_1"
}

Actual local response

{
  "list": {
    "id": "list_1",
    "name": "L",
    "description": null,
    "memberCount": 0,
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: ICP filters over the published actions > lists.members.add_from_filter > refuses missing or archived lists, missing segments, bad sources, complex filters and readers. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured lists.archive · HTTP 200

Action input

{
  "id": "list_2"
}

Actual local response

{
  "list": {
    "id": "list_2",
    "name": "Other",
    "description": null,
    "memberCount": 0,
    "createdAt": "2026-10-01T09:00:00.000Z",
    "updatedAt": "2026-10-01T09:00:00.000Z",
    "archivedAt": "2026-10-01T09:00:00.000Z"
  }
}

Source test: sourcing workflows over the published actions > refuses missing or archived lists, missing segments and a TopoloCRM source. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured lists.archive · HTTP 200

Action input

{
  "id": "list_1"
}

Actual local response

{
  "list": {
    "id": "list_1",
    "name": "Target",
    "description": null,
    "memberCount": 0,
    "createdAt": "2026-10-01T09:00:00.000Z",
    "updatedAt": "2026-10-01T09:00:00.000Z",
    "archivedAt": "2026-10-01T09:00:00.000Z"
  }
}

Source test: sourcing workflows over the published actions > pauses itself when its list is archived or its segment deleted, and records the failure. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Effects and response meaning

• Sets list archivedAt and updatedAt. Active list discovery and active references on contacts omit it, but direct lists.get still reads the record. Stored contacts and memberships are kept.
• Archived lists cannot be edited or have membership changed; repeating archive returns state_conflict. No list-unarchive action is presented. This does not erase contacts or prove outreach was recalled.

Verify the result

• Read lists.get with the retained id and confirm archivedAt. Do not interpret omission from lists.list as deletion of the contacts.

Recover

After an uncertain response, read lists.get. If archivedAt is set, do not repeat archive. No documented unarchive action exists; an unintended archive needs operator review rather than a guessed recreation of its audience.

Refused responses

Captured lists.archive · HTTP 409

Action input

{
  "id": "list_1"
}

Actual local response

{
  "error": {
    "code": "state_conflict",
    "message": "This list is already archived."
  }
}

Source test: audience routes > lists > creates, lists, edits and archives a list. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Error recovery

• HTTP 403 permission_denied: Stop and inspect the permission required by this action in the current credential. Do not broaden permissions or switch organization automatically.
• HTTP 422 invalid_action_input: Correct the request against the current input schema and validate it again before planning.
• HTTP 409 state_conflict: Read the exact retained contact or list and inspect archivedAt. Archived records cannot be edited or have list memberships changed; repeated archive is refused. Do not invent an unarchive operation.

Related actions

• Get prospect list
• List prospect contacts

Evidence and limits

• contracts/audience.mjs

• contracts/audience-filter.mjs

• apps/api/src/audience/audience-routes.ts

• apps/api/src/audience/contacts-handlers.ts

• apps/api/src/audience/contact-search.ts

• apps/api/src/audience/contacts-repository.ts

• apps/api/src/audience/lists-handlers.ts

• apps/api/src/audience/lists-repository.ts

• apps/api/src/audience/filter-source.ts

• apps/api/test/audience-routes.test.ts

• apps/api/test/segments-routes.test.ts

• Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

• Widget/bootstrap use actual app handler but mocked worker runtime and app identity.

• No gateway execution, live permissions, external delivery or deployed proof.

The examples are local route captures with synthetic context and simulated providers. They do not prove live authorization, CLI/MCP gateway execution, production state or delivery.