Mental Model

This is the most important page in the documentation.
If you misunderstand this, you will misintegrate.

The Stripe Analogy

Think of how you integrate Stripe:

• You don't build Stripe into your app—you call Stripe
• Stripe doesn't own your users—you do
• Stripe doesn't render UI—you do
• Stripe doesn't decide your checkout flow—you do

Clearhold works the same way, except instead of payments, we orchestrate escrows and disputes.

Where We Sit in Your Architecture

      graph TD
      User[User] --> App[Your Application]
      App -->|API Calls| Engine[Clearhold Engine]
      Engine -->|Webhooks| App
      subgraph Your_Infrastructure[Your Infrastructure]
      User
      App
      end
      subgraph Clearhold[Clearhold Cloud]
      Engine
      end
      style Engine fill:#1e1e2e,stroke:#6366f1,stroke-width:2px,color:#fff
      style App fill:#1e1e2e,stroke:#a5b4fc,stroke-width:2px,color:#fff
      style User fill:#1e1e2e,stroke:#fff,stroke-width:1px,color:#fff

      linkStyle default stroke:#818cf8,stroke-width:2px
    

Data & Responsibility Boundary

This is non-negotiable:

What This Means Practically

We Store References, Not Content

When you submit evidence for a dispute, you send us a reference:

{
  "reference": {
    "type": "external_reference",
    "provider": "google_drive",
    "uri": "https://drive.google.com/...",
    "content_hash": "sha256:abc123..."
  }
}

We store the hash for integrity verification. We never download or store the actual file.

We Inform, Not Transact

When you create an escrow with total_amount: 50000, we record that information. We don't hold funds. We don't process payments. When our decision engine says "split 60/40", you execute that in your payment system.

We Recommend, You Enforce

Our decision engine produces a recommendation with a confidence score. As the operator, you can accept it as-is, or adjust it within bounds (±30%). The final decision is yours. We just make it defensible.

The Fundamental Question

"Is this the engine's job, or the integrator's job?"

When in doubt, it's your job. We do escrow orchestration. Everything else is your domain.