Skip to main content
Legal standing belongs to an identity. Ava can hold any number of verifications — a case in which each member (an owner, a responsible party) completes a hosted identity check — and any number of companies, each a formation that references a completed verification. Agents reach both through the identity’s grants; there is no separate assignment. The flow is short:
  1. Start a case with POST /v1/identities/{id}/legal/verifications, naming the members.
  2. Give the primary member the returned link; every other member is emailed theirs. The primary is never emailed — their link is on the create response and on every resend, and null on reads.
  3. Read GET /v1/identities/{id}/legal/verifications/{vid} until ready_for_formation is true.
  4. Form a company with POST /v1/identities/{id}/legal/companies — the fee is debited from the organization’s credits first — then file it with POST …/companies/{cid}/submit.
  5. Documents (articles, EIN letter, operating agreement) appear under …/companies/{cid}/documents.
Vetta stores a member’s name and email only. Date of birth, tax ids and home addresses are collected on the hosted page and never cross Vetta’s API, rows or audit log. A hosted link is returned once, on the response that minted it, and is null on every later read; resend mints a new one.

​
Lifecycle

A member is pending → link_ready (or link_sent once emailed) → in_progress → pending_review | verified | failed. verified and failed are final: a redelivered callback or a later read never changes them. The case is failed if any member failed, else pending_review if any member is under review, else verified once every member is, else in_progress. A company is paid the moment it is created — the fee (the formation price plus the state’s filing fee, both integer micro-USD) is debited from the organization’s credits in the same request, and a short balance is refused with insufficient_credits before anything reaches the provider. submit moves it to submitted, then to formed as the provider finishes, or failed with a plain-language failure_reason. failed is not terminal and the fee is not lost: a provider that was throttling, timing out or briefly down leaves the company failed, and submit may be called again — the filing carries the company’s own id as the provider’s idempotency key, so a filing that was accepted before the timeout is answered rather than made twice. required_actions names anything still waiting on a person.

​
Configuration

The Worker needs VETTA_LEGAL_VERIFY_API_KEY, VETTA_LEGAL_VERIFY_PLAYBOOK_KEY, VETTA_LEGAL_WEBHOOK_SECRET and VETTA_LEGAL_FORMATION_API_KEY bound. Without them every route, tool and command answers feature_not_configured; nothing pretends to succeed.

​
Agent tools

When a session selects an identity, its harness receives the legal.* tools. Reads — legal.verifications, legal.verification, legal.companies, legal.company, legal.documents, legal.naics — run under the agent’s ordinary policy. legal.verify, legal.resend_link, legal.form and legal.submit default to ask, including when the agent’s default tool policy is allow, because each one contacts a person, spends credits or files a document. A session with no selected identity receives none of them.

​
Infrastructure as code

A blueprint declares the companies an identity should hold, keyed by label:
up only reports. It names the case’s status and whether a company matching a name option exists, and refuses to start a verification (a person must be on the other end of the hosted page) or to form a company (the organization pays). The refusal names the command a person runs next.

Legal API

Verifications, companies, documents and reference data.