resolve_identity_finding

Resolve a Clerk drift finding

act entity tenant-private since 2026-10-01

Decides a finding list_identity_findings shows. remove takes the Clerk membership away (a membership Trade HQ did not decide). admit, with a role_template_id, makes the person a member with that role, or gives a member whose Clerk role changed that role, and puts Clerk's role to match: never Owner, never a role carrying more than yours, never a membership a directory manages. ignore closes the finding once and changes nothing. Staff may only remove. The same decision again changes nothing.

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first
idempotency: natural
emits: identity_finding.resolved
MCP tool: resolve_identity_finding
decision_set: approve, reject, escalate
REST: POST https://api.containertradehq.com/v1/cap/resolve_identity_finding

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 finding is in.
finding_id	uuid	required	UUID The finding, from list_identity_findings.
decision	one_of	required	one of remove, admit, ignore remove, admit or ignore: one the finding's decisions name.
role_template_id	text	optional	1 to 64 characters For admit: a shipped role template's id or one of the org's own, never owner.

Response

org_id · string · The org.
finding_id · string · The finding.
resolution · string · How it is resolved.
admitted_role_template_id · stringnull · The role template an admit gave.
command · stringnull · The Clerk command the decision queued, if any.

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"
    },
    "finding_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The finding.",
      "x-data-class": "operational"
    },
    "resolution": {
      "type": "string",
      "enum": [
        "removed",
        "admitted",
        "ignored"
      ],
      "description": "How it is resolved.",
      "x-data-class": "operational"
    },
    "admitted_role_template_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The role template an admit gave.",
      "x-data-class": "operational"
    },
    "command": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "membership_remove",
        "role_set",
        null
      ],
      "description": "The Clerk command the decision queued, if any.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "finding_id",
    "resolution",
    "admitted_role_template_id",
    "command"
  ],
  "additionalProperties": false
}

Refusals

finding_not_found · 422 · the org holds no such finding
finding_resolved · 422 · the finding was already resolved with another decision
decision_not_offered · 422 · the decision is not one the finding's kind offers
role_template_required · 422 · admit names the role template to admit with
owner_not_admittable · 422 · nobody is admitted as Owner from a finding
permission_not_held · 422 · the template, or the member's current one, carries a permission the caller's own role in the org does not
unknown_role_template · 422 · the template is neither shipped nor one of the org's
directory_managed · 422 · a directory manages the membership, so its role is the directory's
no_trade_hq_user · 422 · the Clerk user is no Trade HQ user, so there is nobody to admit; invite the person instead
staff_may_only_remove · 422 · staff may only remove

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 drift decision
Outbound: crosses to no counterparty

Events

identity_finding.resolved audit_only

approve_grant, create_invite_link, decide_access_review_item, grant_unit_role, import_users, invite_user, set_member_role

get a test key

curl https://api.containertradehq.com/v1/cap/resolve_identity_finding \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_id>","finding_id":"00000000-0000-4000-8000-000000000000","decision":"remove"}'

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

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.resolveIdentityFinding({
  "org_id": "<org_id>",
  "finding_id": "00000000-0000-4000-8000-000000000000",
  "decision": "remove"
});

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.resolve_identity_finding({
    "org_id": "<org_id>",
    "finding_id": "00000000-0000-4000-8000-000000000000",
    "decision": "remove",
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "resolve_identity_finding",
    "arguments": {
      "org_id": "<org_id>",
      "finding_id": "00000000-0000-4000-8000-000000000000",
      "decision": "remove"
    }
  }
}

MCP

resolve_identity_finding · readOnlyHint false · approval required

“Call resolve_identity_finding”