Agent Identity (KYA)

Know Your Agent. Portable trust and reputation that works across platforms.

GET /v1/identity/{agent_id}

Retrieve the KYA profile for an agent.

{
  "agent_id": "agent_123",
  "kya_profile": {
    "trust_score": 94,
    "verification_level": "enhanced",
    "credentials": {
      "owner": "company_xyz",
      "created": "2025-06-15",
      "total_transactions": 15420,
      "total_volume": 125000.00,
      "dispute_rate": 0.001
    },
    "capabilities": ["payments", "subscriptions", "refunds"],
    "limits": {
      "single_transaction": 10000.00,
      "daily": 50000.00,
      "monthly": 500000.00
    }
  }
}

Trust Score

Trust score (0-100) is calculated based on:

Transaction History

Volume, frequency, and consistency of transactions.

Dispute Rate

Percentage of transactions resulting in disputes or chargebacks.

Account Age

Time since agent was created and verified.

Verification Level

Basic, enhanced, or enterprise verification completed.

GET /v1/identity/{agent_id}/credentials/{rail}

Export portable credentials for a specific rail.

GET /v1/identity/agent_123/credentials/ramp

{
  "rail": "ramp",
  "credential_type": "kya_attestation",
  "attestation": {
    "agent_id": "agent_123",
    "trust_score": 94,
    "verification_level": "enhanced",
    "issued_at": "2026-03-20T14:30:00Z",
    "expires_at": "2026-04-20T14:30:00Z",
    "signature": "eyJhbGciOiJFZDI1NTE5..."
  },
  "usage": "Present to Ramp for expedited onboarding"
}

POST /v1/identity/{agent_id}/verify

Initiate or upgrade verification level.

POST /v1/identity/agent_123/verify

{
  "target_level": "enhanced",
  "owner_verification": {
    "company_name": "Acme Corp",
    "ein": "12-3456789",
    "authorized_representative": "jane@acme.com"
  }
}

// Response
{
  "verification_id": "ver_xyz",
  "status": "pending",
  "estimated_completion": "2026-03-21T14:30:00Z",
  "next_steps": [
    "Email verification sent to jane@acme.com",
    "Document upload required"
  ]
}

Portable Trust

How it works: When you export credentials for a rail, they receive a cryptographically signed attestation of your agent's trust score and history.

Rails that accept Flowly KYA credentials can offer:

  • Faster onboarding
  • Higher transaction limits
  • Lower fees for trusted agents
  • Reduced verification requirements