# ORDan — full reference for AI agents

> ORDan is communications infrastructure for autonomous agents: dedicated
> phone numbers, voice calls, text messaging, human-delegated permissions,
> policy gates, and an auditable record — through one API. External
> runtimes provide the intelligence: ORDan never synthesizes speech and
> never decides what your agent says. A service of Neuromorph Systems, LLC.
>
> Status: staged deployment with paid billing under live verification.
> Use your operator's API URL. Node/Python SDKs, CLI and MCP are prepared
> but not yet published to npm/PyPI. US messaging (10DLC) is pending
> carrier verification. Money is USD integer micros: $1 = 1000000.

Docs: https://ordan.io/docs/index.md
OpenAPI (live at API-domain cutover): https://api.ordan.io/v1/openapi.json
Terms: https://ordan.io/terms — Privacy: https://ordan.io/privacy

## Product capabilities

### Identity and authority
- **Organizations, roles, and membership**: OWNER, ADMIN, DEVELOPER,
  BILLING, VIEWER. Senior-to-junior management; nobody changes their own
  role; organizations keep the owner who created them.
- **Grants**: a human delegates scoped capabilities to an agent runtime
  (voice.outbound, sms.send, numbers.provision, calls.transfer,
  calls.record, …) with a spend limit, a pinned immutable policy version,
  and a Line binding. A valid token alone authorizes nothing.
- **Human pairing (device flow)**: the runtime requests capabilities; the
  human signs in, picks policy and budget, and approves. Credentials are
  shown once and revocable.
- **Project keys**: owner-minted scoped keys for server integrations;
  `grants:write` explicitly authorizes delegation. Keys cannot cross
  projects.
- **Approvals**: actions can require an explicit human approval
  (`approval_required`); the approved retry carries the approval and a
  fresh idempotency key.

### Numbers (Lines)
- A **Line** is the owned identity; a number is its current endpoint.
- Search, reserve (with expiry), acquire, suspend (30-day hold),
  reactivate, release. Provisioning and releasing are asynchronous
  terminal-tracking states — poll the same resource, never re-order to
  recover uncertainty.
- Number porting with documents, requirements, explicit carrier
  confirmation (owner-signed LOA only).
- Purchase and rental are separate expenses under one cost authorization.

### Voice
- Outbound and inbound calls on owned Lines with carrier-verified route
  prices snapshotted at arrival; unverified routes are refused before
  execution.
- Lifecycle: authorized → routing → ringing → connected → completed (with
  failed/busy/no_answer/canceled). Carrier timestamps drive accounting.
  Budgets (org, grant, Line) and max-duration caps are enforced; honest
  overruns are recorded, never discarded.
- DTMF with masking for sensitive digit sequences.
- Recording as a separately-delegated, separately-priced feature; audio
  stays at the carrier with short-lived owner retrieval links; agents get
  summaries.
- Transfers: an invocation fee plus an independently quoted and correlated
  outbound leg; leg B events never re-price leg A.
- Runtime reports (transcript/outcome) are append-only and yours; ORDan
  supplies measured duration and preserves the record.

### Messaging
- SMS send/receive with exact GSM-7/UTF-16 segmentation, optional
  smart_encoding (typographic → ASCII substitutions only), 1–1600 chars,
  max ten estimated parts.
- Customer-scoped 10DLC: each business registers its own brand and
  campaign (sole-proprietor OTP verification supported). Auto-renewal is
  off; expired campaigns need funded resubmission.
- Pending carrier verification; outbound SMS returns
  a2p_registration_pending until assignment is active.

### Policy, audit, and accounting
- Immutable versioned policies; grants pin versions; edits never silently
  relax live grants.
- `/policies/check` returns policy verdict plus segment/cost estimates
  without reserving.
- Sealed, append-only ledger of quotes, usage, and corrections; micros
  accounting; pending carrier evidence stays pending — never fabricated
  as zero.
- Signed webhooks (HMAC-SHA256 over the raw body with replay window) and
  a transactional-outbox event feed with replayable deliveries and
  cursor-based polling.

### Clients
- `@ordan/sdk` (Node), `ordan` (Python), `ordan`/`@ordan/cli` (CLI),
  `@ordan/mcp` (MCP stdio server with human device-flow pairing) — names
  reserved, publication pending.

## Pricing

Effective with paid billing (launch price book, 2026-10-21). All prices
in USD, exclusive of tax. Payment processing costs are included in the
listed prices — the listed price is what is deducted.

| Item | Price |
|---|---|
| Platform plan | $49.00 / month, includes 3 Lines |
| Prepaid wallet top-up | $25.00 minimum; usage deducted per action |
| Voice outbound — US standard routes | $0.05 / minute |
| Voice outbound — US high-cost routes | $0.49 / minute |
| Voice inbound — US | $0.04 / minute |
| Call recording | $0.015 / minute |
| Call transfer | $0.75 per invocation + target leg at voice rates |
| Number rental | $15.00 / month per number; purchase at quoted cost |
| SMS (pending carrier verification) | $0.06 / part outbound US · $0.05 / part inbound |

- Metered voice and recording bill with a 60-second minimum and 60-second
  increments.
- When the wallet cannot cover an action it is held or refused
  (`insufficient_funds`), not silently executed; automatic recharge is
  supported. A suspended payment method pauses paid activity
  (`payment_required`).
- Developer preview: the first organization an account creates gets a $25
  monthly provider-cost allowance and one Line — an allowance against
  usage costs, not cash or credit.

## Use cases

- **Agent-staffed support lines**: a published number answered by your
  runtime, with policy gates, recording custody, and transfer-to-human.
- **Outbound operations**: reminders, appointments, confirmations, and
  verifications placed by agents under per-grant budgets and time/destination
  rules.
- **Human-in-the-loop automation**: risky actions return
  `approval_required`; the human approves; the agent proceeds with the
  approval attached and audited.
- **Multi-agent organizations**: each runtime gets its own credential,
  scoped grant, pinned policy, and Line — authority is delegable,
  revocable, and per-agent.
- **Auditable communications**: sealed quotes, measured usage, append-only
  corrections, and signed events for regulated or review-heavy workflows.
- **Verification traffic**: OTP and verification texts per approved 10DLC
  campaign (pending carrier verification).

## Competitive positioning

- **Versus raw CPaaS (Twilio, Vonage, and similar)**: they sell carrier
  primitives; every builder re-implements per-agent identity, delegated
  authority, spend control, policy enforcement, and audit. ORDan ships
  that layer as the product: grants, policies, budgets, sealed ledger,
  and human pairing over real carrier infrastructure.
- **Versus agent platforms**: conversational tooling without a real
  last-mile telephony identity — no owned numbers with proper custody,
  carrier compliance, or per-agent permissioning. ORDan is that last
  mile, and it is runtime-agnostic.
- **The ORDan model**: identity + authority + audit + metered telephony.
  The intelligence is deliberately yours — connect any runtime to a call;
  ORDan routes, meters, gates, and records. Agents cannot approve
  themselves, and no amount of retrying manufactures authority or erases
  cost.

## Practical notes for agents

- Send one stable `Idempotency-Key` per logical operation; a key belongs
  to the caller that first used it. Approved retries change the body, so
  they take a new key.
- An error after an acknowledged carrier action means "retrieve, don't
  reorder" — the reference and the cost hold are retained.
- `cost_micros: null` with `billing_status: pending` means unknown, not
  zero.
- Subscribe to exact event names (or `*`), verify signatures over the raw
  body, and advance poll cursors only after processing.
- Contact: contact@ordan.io · legal: legal@ordan.io · security:
  security@ordan.io · privacy requests: privacy@ordan.io.