Contract
- shape
- entity
- authority
- act
- evidence
- none
- subscription
- false
- permission
- any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
- idempotency
- natural
- emits
- my_settings.changed
- MCP tool
- set_my_settings
- decision_set
- approve, reject
- REST
- POST https://api.containertradehq.com/v1/cap/set_my_settings
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 the caller is a member of, whose levels above the caller decide what they may set. |
| settings | my_settings | required | The keys to change: each to a value, or to null to clear the caller's own value. |
Response
org_id· string · The org.settings· object · Every key's effective value for the caller in the org, where it came from, and where it is locked.
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"
},
"settings": {
"type": "object",
"properties": {
"base_currency": {
"type": "object",
"properties": {
"value": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "The ISO 4217 currency the books are kept in. An org decides it; its units and people do not."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"date_format": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD/MM/YYYY",
"MM/DD/YYYY"
],
"description": "How dates are shown."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"fiscal_year_start": {
"type": "object",
"properties": {
"value": {
"type": "string",
"pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$",
"description": "The first day of the fiscal year, MM-DD. An org decides it; its units and people do not."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"locale": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"en-US",
"en-GB",
"de-DE",
"fr-FR",
"es-ES",
"nl-NL"
],
"description": "The language and regional format of the interface."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_booking": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How bookings are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_invoice": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How invoices are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_order": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How sales orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_purchase_order": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How purchase orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_release": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How releases are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. A yard may number its own."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_vendor_bill": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How vendor bills are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"shell_last_tab": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"depots",
"sell",
"source",
"intel"
],
"description": "The tab of the app's header a person last chose, which they land on when they sign in."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"timezone": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^(UTC|[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)+)$",
"description": "The IANA time zone times are shown in."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"units_of_measure": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"metric",
"imperial"
],
"description": "Metric or imperial weights and dimensions. An org decides it for everyone in it."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"week_starts_on": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"monday",
"sunday"
],
"description": "The first day of a week in calendars and weekly reports."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
}
},
"required": [
"base_currency",
"date_format",
"fiscal_year_start",
"locale",
"numbering_series_booking",
"numbering_series_invoice",
"numbering_series_order",
"numbering_series_purchase_order",
"numbering_series_release",
"numbering_series_vendor_bill",
"shell_last_tab",
"timezone",
"units_of_measure",
"week_starts_on"
],
"additionalProperties": false,
"description": "Every key's effective value for the caller in the org, where it came from, and where it is locked.",
"x-data-class": "operational"
}
},
"required": [
"org_id",
"settings"
],
"additionalProperties": false
} Refusals
setting_locked· 422 · the platform, the org's account or the org locked this key
The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.
Surfaces
DesktopF
MobileF
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
- MCP: approval required
- Voice: degraded: confirmation
- OneBox: no document originates a person's settings
- Outbound: crosses to no counterparty
Events
my_settings.changedaudit_only