ReturnAccountShareResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gtm-api/main/json-schema/gtm-api-return-account-share-response-schema.json",
  "title": "ReturnAccountShareResponse",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gtm-api-id-openapi.yaml#/components/schemas/ReturnAccountShareResponse",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "enum": [
        true
      ]
    },
    "operation": {
      "type": "string",
      "enum": [
        "action"
      ]
    },
    "action": {
      "type": "string",
      "description": "kebab-case verb; matches the route segment."
    },
    "item": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "sid": {
          "type": "string"
        },
        "team_sid": {
          "type": "string",
          "description": "The OWNER team: the row tenant, the side that lent the account out."
        },
        "channel": {
          "type": "string",
          "enum": [
            "linkedin",
            "email"
          ],
          "description": "Which channel service owns the physical account pair."
        },
        "to_team_sid": {
          "type": "string",
          "description": "The HOLDER team: the side that borrowed the account."
        },
        "to_user_sid": {
          "type": [
            "string",
            "null"
          ],
          "description": "Resolved user when the share was targeted by email; null when targeted by team sid."
        },
        "to_email": {
          "type": [
            "string",
            "null"
          ],
          "description": "The targeting input kept for audit; null when targeted by team sid."
        },
        "owner_cluster_id": {
          "type": "integer"
        },
        "holder_cluster_id": {
          "type": "integer"
        },
        "owner_account_sid": {
          "type": "string",
          "description": "The owner's channel account row, parked for the duration of the loan. Prefix agnostic: ln_ac_ on LinkedIn, em_ac_ on email."
        },
        "owner_channel_ref": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque second row the channel needs to name (LinkedIn puts its ab_br_ browser sid here); null when the channel needs none."
        },
        "holder_account_sid": {
          "type": [
            "string",
            "null"
          ],
          "description": "The holder's copy. NULL until the copy phase lands, so it is null on every pre-active row."
        },
        "holder_channel_ref": {
          "type": [
            "string",
            "null"
          ]
        },
        "owner_account_label": {
          "type": [
            "string",
            "null"
          ],
          "description": "The channel's display name for the lent account, e.g. \"Jane Roe (jane-roe)\". Use it to tell one share from another when reporting to a human. Null when the channel had no name to give. Display only: never filter, match or reason on it."
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "owner_parked",
            "active",
            "closing",
            "holder_released",
            "rolling_back",
            "returned",
            "recalled",
            "failed"
          ],
          "description": "The durable phase, and the answer to \"did the loan start\". Only active means the holder can work."
        },
        "holder_over_slot": {
          "type": "boolean",
          "description": "True when the holder had no free account slot at create, so the copy landed in the channel's subscription hold. The loan still reaches active; the holder cannot work until it upgrades."
        },
        "end_reason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "returned_by_holder",
            "recalled_by_owner",
            "holder_deleted_copy",
            "holder_team_purged",
            "owner_team_purged"
          ],
          "description": "Stamped when an ending is REQUESTED. Only ever set on a row that reached active."
        },
        "failure_reason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "park_failed",
            "export_failed",
            "copy_refused",
            "probe_stale",
            "team_purged"
          ],
          "description": "Why a pre-active phase gave up. Non null on exactly rolling_back and failed."
        },
        "planned_return_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Informational only. When it passes the owner is emailed a recall link once; there is NO auto return."
        },
        "expiry_notified_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "phase_claimed_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "phase_attempts": {
          "type": "integer",
          "description": "Attempts on the CURRENT phase, reset on every advance. A large and growing value is the stuck signal on a phase that may not give up."
        },
        "ended_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "ended_by": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "actor_type": {
              "type": "string",
              "enum": [
                "user",
                "support",
                "api_key",
                "system",
                "agent"
              ]
            },
            "actor_sid": {
              "type": [
                "string",
                "null"
              ]
            },
            "team_sid": {
              "type": "string"
            },
            "actor_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "The OAuth client that acted (\"Claude\", \"n8n\"); null for a user, an API key or a system job."
            },
            "oauth_client_sid": {
              "type": [
                "string",
                "null"
              ],
              "description": "The acting OAuth client (id_oc_*); null off the OAuth path."
            },
            "reason": {
              "type": [
                "string",
                "null"
              ],
              "description": "Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise."
            },
            "permissions": {
              "type": "object",
              "additionalProperties": {},
              "description": "Internal audit context: the grant set the actor held at write time. Not a contract."
            },
            "cluster_id": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Internal audit context: the cluster that served the write."
            },
            "trace_id": {
              "type": [
                "string",
                "null"
              ],
              "description": "Internal audit context: the trace id of the request that wrote the row."
            }
          },
          "required": [
            "actor_type",
            "actor_sid",
            "team_sid",
            "permissions"
          ],
          "description": "Who ended it. The machine readable why is end_reason (an ending) or failure_reason (a failure), never this blob."
        },
        "created_by": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "actor_type": {
              "type": "string",
              "enum": [
                "user",
                "support",
                "api_key",
                "system",
                "agent"
              ]
            },
            "actor_sid": {
              "type": [
                "string",
                "null"
              ]
            },
            "team_sid": {
              "type": "string"
            },
            "actor_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "The OAuth client that acted (\"Claude\", \"n8n\"); null for a user, an API key or a system job."
            },
            "oauth_client_sid": {
              "type": [
                "string",
                "null"
              ],
              "description": "The acting OAuth client (id_oc_*); null off the OAuth path."
            },
            "reason": {
              "type": [
                "string",
                "null"
              ],
              "description": "Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise."
            },
            "permissions": {
              "type": "object",
              "additionalProperties": {},
              "description": "Internal audit context: the grant set the actor held at write time. Not a contract."
            },
            "cluster_id": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Internal audit context: the cluster that served the write."
            },
            "trace_id": {
              "type": [
                "string",
                "null"
              ],
              "description": "Internal audit context: the trace id of the request that wrote the row."
            }
          },
          "required": [
            "actor_type",
            "actor_sid",
            "team_sid",
            "permissions"
          ]
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      },
      "required": [
        "sid",
        "team_sid",
        "channel",
        "to_team_sid",
        "to_user_sid",
        "to_email",
        "owner_cluster_id",
        "holder_cluster_id",
        "owner_account_sid",
        "owner_channel_ref",
        "holder_account_sid",
        "holder_channel_ref",
        "owner_account_label",
        "status",
        "holder_over_slot",
        "end_reason",
        "failure_reason",
        "planned_return_at",
        "expiry_notified_at",
        "phase_claimed_at",
        "phase_attempts",
        "ended_at",
        "ended_by",
        "created_by",
        "created_at",
        "updated_at"
      ]
    },
    "result": {
      "type": "object",
      "properties": {
        "closing_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Shares this call stamped closing. The teardown is the driver's, so this is never \"recalled\" or \"returned\"."
        },
        "total_matched": {
          "type": "integer",
          "minimum": 0,
          "description": "True count of active shares the target set held. closing_count below this means a remainder is left; re-read the count before the next call."
        }
      },
      "required": [
        "closing_count",
        "total_matched"
      ]
    },
    "meta": {
      "type": "object",
      "properties": {
        "trace_id": {
          "type": "string",
          "description": "UUID v7; same 128-bit value as the X-Trace-Id header."
        },
        "span_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{16}$",
          "description": "16 hex chars, root span of this request."
        },
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 UTC (Y-m-dTH:i:sZ), response time."
        },
        "duration_ms": {
          "type": "integer",
          "minimum": 0,
          "description": "Server-side wall clock."
        },
        "team_sid": {
          "type": [
            "string",
            "null"
          ],
          "description": "The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends."
        },
        "actor_type": {
          "type": [
            "string",
            "null"
          ],
          "description": "user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends."
        }
      },
      "required": [
        "trace_id",
        "span_id",
        "timestamp",
        "duration_ms"
      ]
    }
  },
  "required": [
    "success",
    "operation",
    "action",
    "item",
    "result",
    "meta"
  ]
}