Book a demo

get_data_policy

Get a role template's data policy

read entity tenant-private since 2026-10-01

Returns one role template's data policy: 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; a clone answers its own, or its source's until it has one. Operational fields are always read and exported.

Contract

shape
entity
authority
read
evidence
none
subscription
false
permission
any one of: role.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
get_data_policy
REST
POST https://api.containertradehq.com/v1/cap/get_data_policy

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose role template it is.
role_idtextrequired1 to 20 characters
The role template: a shipped id or one of the org's clone ids.

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

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

Surfaces

DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates a data policy
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

delete_role_template, set_data_policy, update_role_template