get_principal

​

When to call

• Verify identity before configuration. A recognized result exposes the seller-resolved principal_kind and existing principal_id before the first state-changing call.
• Bootstrap the concurrency fence. Read configuration_version before a guarded sync_principal replacement instead of writing blind.
• Recover after local-state loss. A restarted service reads principal_id, configuration_version, every destination_ref, and each destination’s setup state before deciding what to sync.
• Observe setup progress. After a destination returns action_required or validating, poll here until it reaches ready — or subscribe to the principal.changed webhook and use this read as the repair path. Polling never disturbs the version fence.
• Read the negotiated async contract. The declarations state carries both the declared set and the seller-computed accepted intersection that governs webhook payload versions and signing algorithms.
• Read reporting subscriptions (experimental, 3.3). When the seller supports the reporting_subscriptions section, each subscription returns its state (active, inactive, or action_required with issues), accepted_at for the current subscription_version (coverage starts at the first boundary at or after the latest of it, each buy’s confirmed_at, and the account’s authorized_at), prior_versions with their accepted_at while retained, the bound destination_ref, and its configuration. Deactivated subscriptions stay listed as inactive with deactivated_at while their obligations are retained. accounts_with_exceptions[] lists each account with an open coverage exception and its reasons, so a caller need not poll every account. Accounts whose authority the caller lost appear under accounts_unauthorized[] with unauthorized_at, last_owed_period_end, and withheld_period_count (and optionally the withheld obligation IDs), with no current account data, until re-grant or for status_retention_days; after that a re-grant is a fresh coverage start. Changes to either list, and a subscription moving to action_required, fire principal.changed with reason reporting_subscription_changed. Per-account coverage and exclusions for authorized accounts are read through get_reporting_status.
• Audit generations. Superseded generations appear in each destination’s prior_destination_refs; revoked destinations appear in retired_destinations. Both remain resolvable for existing authorized account bindings and retained reporting history.

​

Identity

​

Results

​

Relationship status

{
  "status": "completed",
  "result": {
    "kind": "unconfigured",
    "relationship": {
      "status": "pending_approval",
      "setup": {
        "url": "https://streamhaus.example/partners/applications/7k3q",
        "message": "Upload your billing entity details to finish the agent-billing application."
      }
    }
  }
}

{
  "status": "completed",
  "result": {
    "kind": "recognized",
    "principal_kind": "buyer_agent",
    "principal_id": "prin_01K4C6RGT5Q18VCPGXE7DDWQ5F"
  }
}

{
  "status": "completed",
  "result": {
    "kind": "unconfigured"
  }
}

{
  "status": "completed",
  "result": {
    "kind": "current",
    "principal_id": "prin_01K4C6RGT5Q18VCPGXE7DDWQ5F",
    "principal_kind": "buyer_agent",
    "configuration_version": "cfg_01K4C6V2N5PC1TQAH9WTT8D2HP",
    "configuration": {
      "notification_configs": [],
      "reporting_destinations": [
        {
          "destination_id": "analytics-warehouse",
          "destination_ref": "dest_01K4C6T6Q0A9E6Y3N1FQ1T8YKV",
          "prior_destination_refs": ["dest_01K4C5A2M9XPZ0T4B7QCW3JHRD"],
          "state": "ready",
          "configuration": {
            "pattern": "warehouse_materialization",
            "destination_id": "analytics-warehouse",
            "active": true,
            "provider": { "domain": "data-warehouse.example" },
            "transport": "bigquery",
            "location": "pinnacle-analytics.adcp_reporting",
            "accepted_verification_profiles": ["native_commit", "canonical_digest"]
          }
        }
      ]
    }
  }
}