set_data_policy

Set a role template's data policy

act entity tenant-private since 2026-10-01

Sets one of the org's own role templates' data policy, whole: which records its members reach (record_scope) and, for commercial, financial and personal fields, whether they read them (allowed, masked or denied) and export them (allowed or denied). A shipped template's data policy is read-only; clone it first. Takes role.manage and a template carrying org.admin. Sending the same data policy again changes nothing.

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: role.manage (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: natural
emits: data_policy.changed
MCP tool: set_data_policy
decision_set: approve, reject, edit
REST: POST https://api.containertradehq.com/v1/cap/set_data_policy

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org whose role template it is.
role_id	text	required	1 to 20 characters One of the org's clone ids. A shipped template is refused.
record_scope	one_of	required	one of whole_org, unit_subtree, portfolio, party_seat Which records its members reach: whole_org, or party_seat for a Counterparty clone.
commercial_read	one_of	required	one of allowed, masked, denied Commercial fields: allowed, masked or denied.
commercial_export	one_of	required	one of allowed, denied Commercial fields in an export: allowed or denied.
financial_read	one_of	required	one of allowed, masked, denied Financial fields: allowed, masked or denied.
financial_export	one_of	required	one of allowed, denied Financial fields in an export: allowed or denied.
personal_read	one_of	required	one of allowed, masked, denied Personal fields: allowed, masked or denied.
personal_export	one_of	required	one of allowed, denied Personal fields in an export: allowed or denied.

Response

org_id · string · The org.
role_id · string · The role template: a shipped id such as read_only, or a clone's RT id.
source · string · shipped: the template's own, read-only; own: the clone's own row; inherited: a clone with no row, answered its source's.
version · integer · The clone's own data policy's version; 0 for a shipped or inherited one.
record_scope · string · Which records its members reach: whole_org, unit_subtree, portfolio or party_seat.
record_scope_locked · boolean · A Counterparty template, or a clone of one, is locked to its party's seat.
commercial_read · string · Commercial fields (acquisition cost, margin, supplier price, FX override): allowed, masked or denied.
commercial_export · string · Whether an export carries commercial fields: allowed or denied.
financial_read · string · Financial fields (invoice totals, credit terms): allowed, masked or denied.
financial_export · string · Whether an export carries financial fields: allowed or denied.
personal_read · string · Personal fields (member emails, phone numbers): allowed, masked or denied.
personal_export · string · Whether an export carries personal fields: allowed or denied.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org.",
      "x-data-class": "operational"
    },
    "role_id": {
      "type": "string",
      "description": "The role template: a shipped id such as read_only, or a clone's RT id.",
      "x-data-class": "operational"
    },
    "source": {
      "type": "string",
      "enum": [
        "shipped",
        "own",
        "inherited"
      ],
      "description": "shipped: the template's own, read-only; own: the clone's own row; inherited: a clone with no row, answered its source's.",
      "x-data-class": "operational"
    },
    "version": {
      "type": "integer",
      "description": "The clone's own data policy's version; 0 for a shipped or inherited one.",
      "x-data-class": "operational"
    },
    "record_scope": {
      "type": "string",
      "enum": [
        "whole_org",
        "unit_subtree",
        "portfolio",
        "party_seat"
      ],
      "description": "Which records its members reach: whole_org, unit_subtree, portfolio or party_seat.",
      "x-data-class": "operational"
    },
    "record_scope_locked": {
      "type": "boolean",
      "description": "A Counterparty template, or a clone of one, is locked to its party's seat.",
      "x-data-class": "operational"
    },
    "commercial_read": {
      "type": "string",
      "enum": [
        "allowed",
        "masked",
        "denied"
      ],
      "description": "Commercial fields (acquisition cost, margin, supplier price, FX override): allowed, masked or denied.",
      "x-data-class": "operational"
    },
    "commercial_export": {
      "type": "string",
      "enum": [
        "allowed",
        "denied"
      ],
      "description": "Whether an export carries commercial fields: allowed or denied.",
      "x-data-class": "operational"
    },
    "financial_read": {
      "type": "string",
      "enum": [
        "allowed",
        "masked",
        "denied"
      ],
      "description": "Financial fields (invoice totals, credit terms): allowed, masked or denied.",
      "x-data-class": "operational"
    },
    "financial_export": {
      "type": "string",
      "enum": [
        "allowed",
        "denied"
      ],
      "description": "Whether an export carries financial fields: allowed or denied.",
      "x-data-class": "operational"
    },
    "personal_read": {
      "type": "string",
      "enum": [
        "allowed",
        "masked",
        "denied"
      ],
      "description": "Personal fields (member emails, phone numbers): allowed, masked or denied.",
      "x-data-class": "operational"
    },
    "personal_export": {
      "type": "string",
      "enum": [
        "allowed",
        "denied"
      ],
      "description": "Whether an export carries personal fields: allowed or denied.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "role_id",
    "source",
    "version",
    "record_scope",
    "record_scope_locked",
    "commercial_read",
    "commercial_export",
    "financial_read",
    "financial_export",
    "personal_read",
    "personal_export"
  ],
  "additionalProperties": false
}

Refusals

unknown_role_template · 422 · the role template is neither shipped nor one of this org's own
shipped_template_read_only · 422 · a shipped role template's data policy is read-only; clone the template and set the clone's
record_scope_not_built · 422 · unit_subtree and portfolio narrow nothing yet; use whole_org
record_scope_locked · 422 · a Counterparty template is locked to its party's seat
party_seat_needs_a_counterparty_template · 422 · only a Counterparty template's members hold a party whose seats a data policy can scope to
org_admin_required · 422 · until step-up assurance exists (TRA-487), changing a data policy takes a role template carrying org.admin as well as role.manage

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileD5

APIF

MCPF*

VoiceD5

PushF

OneBoxN

OutboundN

Mobile: degraded: composition
MCP: approval required
Voice: degraded: composition
OneBox: no document originates a data policy change
Outbound: crosses to no counterparty

Events

data_policy.changed audit_only

delete_role_template, get_data_policy, update_role_template

get a test key

curl https://api.containertradehq.com/v1/cap/set_data_policy \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_id>","role_id":"<role_id>","record_scope":"whole_org","commercial_read":"allowed","commercial_export":"allowed","financial_read":"allowed","financial_export":"allowed","personal_read":"allowed","personal_export":"allowed"}'

import { TradeHQ } from '@containertradehq/sdk';

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.setDataPolicy({
  "org_id": "<org_id>",
  "role_id": "<role_id>",
  "record_scope": "whole_org",
  "commercial_read": "allowed",
  "commercial_export": "allowed",
  "financial_read": "allowed",
  "financial_export": "allowed",
  "personal_read": "allowed",
  "personal_export": "allowed"
});

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.set_data_policy({
    "org_id": "<org_id>",
    "role_id": "<role_id>",
    "record_scope": "whole_org",
    "commercial_read": "allowed",
    "commercial_export": "allowed",
    "financial_read": "allowed",
    "financial_export": "allowed",
    "personal_read": "allowed",
    "personal_export": "allowed",
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_data_policy",
    "arguments": {
      "org_id": "<org_id>",
      "role_id": "<role_id>",
      "record_scope": "whole_org",
      "commercial_read": "allowed",
      "commercial_export": "allowed",
      "financial_read": "allowed",
      "financial_export": "allowed",
      "personal_read": "allowed",
      "personal_export": "allowed"
    }
  }
}

MCP

set_data_policy · readOnlyHint false · approval required

“Call set_data_policy”