Book a demo

get_identity_sync

Get an org's Clerk sync state

read entity tenant-private since 2026-10-01

Answers how an org's Clerk sync stands: when the reconcile last finished for it (nightly at 02:00 PT), how many role differences, memberships Trade HQ did not decide and missing memberships are open, what the org's drift setting does with them (quarantined or alerted), and how many of Clerk's events for it are waiting or failed, the failed ones named.

Contract

shape
entity
authority
read
evidence
none
subscription
false
permission
any one of: staff.read (the staff role staff_read 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
safe
emits
none
MCP tool
get_identity_sync
REST
POST https://api.containertradehq.com/v1/cap/get_identity_sync

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose Clerk sync to read.

Response

  • org_id · string · The org.
  • last_run_at · stringnull · When the newest reconcile covering the org finished; null before the first.
  • last_run_trigger · stringnull · Whether it was the nightly run or a manual one.
  • role_differences · integer · Open role_mismatch findings.
  • unexpected_memberships · integer · Open membership_unexpected findings.
  • missing_memberships · integer · Open membership_missing findings.
  • drift_policy · string · What the org's drift setting does with a difference: quarantined (refused here and put back in Clerk) or alerted (raised only).
  • events_waiting · integer · Clerk's events for the org not yet processed.
  • events_failed · integer · Clerk's events for the org that failed five times and wait for a person.
  • failed_events · string[] · The newest failed events, at most twenty, each as `<when> <kind> <error>`.
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"
    },
    "last_run_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the newest reconcile covering the org finished; null before the first.",
      "x-data-class": "operational"
    },
    "last_run_trigger": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "nightly",
        "manual",
        null
      ],
      "description": "Whether it was the nightly run or a manual one.",
      "x-data-class": "operational"
    },
    "role_differences": {
      "type": "integer",
      "description": "Open role_mismatch findings.",
      "x-data-class": "operational"
    },
    "unexpected_memberships": {
      "type": "integer",
      "description": "Open membership_unexpected findings.",
      "x-data-class": "operational"
    },
    "missing_memberships": {
      "type": "integer",
      "description": "Open membership_missing findings.",
      "x-data-class": "operational"
    },
    "drift_policy": {
      "type": "string",
      "enum": [
        "quarantined",
        "alerted"
      ],
      "description": "What the org's drift setting does with a difference: quarantined (refused here and put back in Clerk) or alerted (raised only).",
      "x-data-class": "operational"
    },
    "events_waiting": {
      "type": "integer",
      "description": "Clerk's events for the org not yet processed.",
      "x-data-class": "operational"
    },
    "events_failed": {
      "type": "integer",
      "description": "Clerk's events for the org that failed five times and wait for a person.",
      "x-data-class": "operational"
    },
    "failed_events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The newest failed events, at most twenty, each as `<when> <kind> <error>`.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "last_run_at",
    "last_run_trigger",
    "role_differences",
    "unexpected_memberships",
    "missing_memberships",
    "drift_policy",
    "events_waiting",
    "events_failed",
    "failed_events"
  ],
  "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 sync state
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.