Legal

Every route is nested under an identity. {identity} accepts an idn_… id or the identity’s name. An identity may hold any number of verifications (a case with one or more members who each complete a hosted verification) and companies (a formation that references a verified case). Money is integer micro-USD (1 USD = 1000000).

On a deployment with no legal provider bound, every route below answers 501 feature_not_configured.

Verifications

List verifications

GET /v1/identities/{identity}/legal/verifications — scope agents:read Returns a paginated list of legal_verification objects, newest first.

Start a verification

POST /v1/identities/{identity}/legal/verifications — scope billing:write

{
  "members": [
    { "first_name": "Ava", "last_name": "Stone", "email": "ava@example.com",
      "role": "primary", "is_responsible_party": true, "ownership_percent": 100 }
  ]
}

Exactly one member is primary and exactly one is the responsible party; ownership percentages sum to 100. Answers 201 with the case; the primary member’s link_url is set on this response only, and every secondary member is emailed their own link (a secondary who could not be emailed gets link_url here too). Honours Idempotency-Key.

{
  "id": "lgv_01j9x2k7q4m8n3p5r6s7t8v9wa",
  "object": "legal_verification",
  "identity_id": "idn_01j9x2k7q4m8n3p5r6s7t8v9wb",
  "status": "in_progress",
  "ready_for_formation": false,
  "members": [
    { "id": "lgm_01j9x2k7q4m8n3p5r6s7t8v9wc", "object": "legal_member",
      "verification_id": "lgv_01j9x2k7q4m8n3p5r6s7t8v9wa",
      "first_name": "Ava", "last_name": "Stone", "email": "ava@example.com",
      "role": "primary", "is_responsible_party": true, "ownership_percent": 100,
      "status": "link_ready", "link_url": "https://verify.example.com/s/…",
      "link_expires_at": "2026-09-09T00:00:00Z", "completed_at": null }
  ],
  "started_at": "2026-09-08T00:00:00Z", "completed_at": null,
  "created_at": "2026-09-08T00:00:00Z", "updated_at": "2026-09-08T00:00:00Z"
}

Member status moves pending → link_ready | link_sent → in_progress → pending_review | verified | failed. verified and failed are terminal and are never changed by a later callback or read. The case is failed if any member failed, else pending_review if any member is under review, else verified once every member is verified, else in_progress.

Read a verification

GET /v1/identities/{identity}/legal/verifications/{verification} — scope agents:read The case with its members, link_url always null. Each unfinished member’s status is refreshed from the provider on this read, so a missed callback is caught up. ready_for_formation is true once every member is verified.

Complete a member

POST /v1/identities/{identity}/legal/verifications/{verification}/members/{member}/complete — scope billing:write Pass { "token": "…" } from the hosted page’s redirect. Answers the legal_member.

Resend a member’s link

POST /v1/identities/{identity}/legal/verifications/{verification}/members/{member}/resend — scope billing:write Mints a fresh hosted link for a member who has not finished. Answers the legal_member with link_url set. A verified or failed member answers state_conflict.

Companies

List companies

GET /v1/identities/{identity}/legal/companies — scope agents:read

Form a company

POST /v1/identities/{identity}/legal/companies — scope billing:write

{
  "verification_id": "lgv_…",
  "state": "WY",
  "name_options": ["Acme Labs"],
  "naics_code": "541511",
  "description": "Software consulting",
  "mailing_address": { "line1": "1 Main St", "line2": null, "city": "Cheyenne", "state": "WY", "postal_code": "82001", "country": "US" }
}

The verification must be verified (state_conflict otherwise). The fee — the formation price plus the state’s filing fee, both reported by GET /v1/legal/states — is debited from the organization’s credits before anything is filed; a short balance answers 402 insufficient_credits. Name endings are canonicalised to LLC. Answers 201 with status paid. Honours Idempotency-Key.

{
  "id": "lgc_01j9x2k7q4m8n3p5r6s7t8v9wd",
  "object": "legal_company",
  "identity_id": "idn_01j9x2k7q4m8n3p5r6s7t8v9wb",
  "verification_id": "lgv_01j9x2k7q4m8n3p5r6s7t8v9wa",
  "status": "paid",
  "entity_type": "llc",
  "state": "WY",
  "name_options": [{ "name": "Acme Labs", "ending": "LLC" }],
  "legal_name": null,
  "naics_code": "541511",
  "description": "Software consulting",
  "mailing_address": { "line1": "1 Main St", "line2": null, "city": "Cheyenne", "state": "WY", "postal_code": "82001", "country": "US" },
  "ein_status": "none",
  "price_micro_usd": 449000000,
  "required_actions": [],
  "failure_reason": null,
  "submitted_at": null, "formed_at": null,
  "created_at": "2026-09-08T00:00:00Z", "updated_at": "2026-09-08T00:00:00Z"
}

price_micro_usd is what was debited: 449000000 is $449.00.

Read a company

GET /v1/identities/{identity}/legal/companies/{company} — scope agents:read Status moves awaiting_payment → paid → submitted → formed | failed. required_actions lists anything a person still has to do.

Submit a company

POST /v1/identities/{identity}/legal/companies/{company}/submit — scope billing:write Files the formation. Idempotent once submitted (a second call answers the same submitted company); a company that already failed answers state_conflict. A provider refusal is recorded as status failed with a provider-neutral failure_reason and answered as the company, not as an error.

Documents

GET /v1/identities/{identity}/legal/companies/{company}/documents — scope agents:read GET /v1/identities/{identity}/legal/companies/{company}/documents/{document} — scope agents:read The first lists legal_document objects (kind is articles, ein_letter, operating_agreement or other); the second answers a short-lived legal_document_link:

{ "object": "legal_document_link", "url": "https://files.example.com/…", "expires_at": "2026-09-08T01:00:00Z" }

Reference data

GET /v1/legal/naics_codes?q=software — scope agents:read GET /v1/legal/states — scope agents:read Both are paginated. naics_code is { "code", "title" }; legal_state carries the state’s filing fee, which is added to the formation price:

{ "object": "legal_state", "code": "WY", "name": "Wyoming", "formation_fee_micro_usd": 100000000 }

Verification callback

POST /v1/webhooks/legal — no scope; the verification provider calls it The provider’s signature is verified over the raw body before anything is parsed; a body that does not verify answers 401 unauthorized. A verified event flips the named member to verified, failed or pending_review and recomputes the case. A member already in a terminal state is left as it is, so a redelivered event changes nothing. Answers 202 { "object": "legal_webhook", "accepted": true | false }; false means the event named a member this deployment does not hold or one already settled.

Errors

validation_failed for member, name, state and description rules; state_conflict for a company on an unverified case or a second submit of a failed one; job_not_ready when reference data cannot be answered right now; insufficient_credits; feature_not_configured. See Errors.

Introduction

Core resources

Platform

Identity

Verifications

List verifications

Start a verification

Read a verification

Complete a member

Resend a member’s link

Companies

List companies

Form a company

Read a company

Submit a company

Documents

Reference data

Verification callback

Errors

​Verifications

​List verifications

​Start a verification

​Read a verification

​Complete a member

​Resend a member’s link

​Companies

​List companies

​Form a company

​Read a company

​Submit a company

​Documents

​Reference data

​Verification callback

​Errors

Verifications

List verifications

Start a verification

Read a verification

Complete a member

Resend a member’s link

Companies

List companies

Form a company

Read a company

Submit a company

Documents

Reference data

Verification callback

Errors