Core API Docs | Sovereign Foundry

Sovereign Foundry

A filed, versioned policy administration core with the front end left to you. Rating, forms, signatures, issuance, billing and earned premium stay inside the core; every screen your buyers touch is yours to build.

Integration specifications

Public interface reference · v1 · reviewed 10/08/2026. Current capabilities are distinguished from partner requirements needing additional work.

OpenAPI 3.0 JSON Guide · Markdown Connect to Sovereign

Import the JSON into Postman or Swagger Editor. Variable response shapes are labelled explicitly; confirm the agreed payloads in the sandbox before generating a production client.

Mobile & portal capability matrix

Policy, drivers & vehicles

Available

GET /policies/{id} returns a header and profile with drivers and vehicles. IDs are UUIDs, not policy numbers; sensitive fields are partly masked.

Billing

Available

GET /policies/{id}/billing returns charges, schedule, paid cents, balance cents and next due. This is not a payment intent or cancellation-cure quote.

Documents

Metadata only

GET /policies/{id}/documents lists IDs, titles, kind and creation date; no downloadable content or insured share links.

Quote → application → signatures

Sandbox workflow

Use the checkout sequence below. Filed constraints, forms and required attestations come from Sovereign.

Live bind / payments

Not available

Production bind is explicitly blocked pending processor-verified payments. There is no general payments/submit endpoint.

FNOL / claims

Contract required

No public claim-submission or claim-status endpoint exists in v1. Agree loss fields, attachments, coverage checks and acknowledgment first.

Insured login / linking

Contract required

A licensee API key is not individual insured authentication. Agree server-enforced ownership mapping before using real policies.

Telematics / underwriting reports

Provider adapter required

No v1 trip, score or report-ingestion endpoint exists. Provider APIs require separately commissioned adapters; a catalog listing is not a working connection.

Integrator questions & answers

Is this public information?

Yes: interface contracts, not credentials, database access, rating algorithms or proprietary models. Public docs grant no operational access. Each partner needs licensee approval and scoped credentials.

Does this cover Xemplar, Verisk and processors?

This is the Sovereign-facing baseline. Apps and raters call Sovereign; providers and processors generally supply APIs Sovereign must call. Bidirectional integrations need both contracts. The questionnaire captures the direction, fields, underwriting checkpoints and commercial permissions.

Where do keys and insured authentication belong?

Keys belong only on a trusted partner server, never in a mobile app or browser. Authorization: Bearer and x-api-key are supported. Read scope can list the licensee’s policies: it must not be exposed directly to consumers. Agree insured ownership verification, consent, recovery and revocation before production. Policy number plus ZIP or DOB alone is not a production identity solution.

Who computes money and dates?

Sovereign supplies authoritative booked premium and cash schedules. Money uses integer cents, dates YYYY-MM-DD, timestamps UTC; display dates MM/DD/YYYY. Do not infer a payment intent, cancellation cure or coverage decision from an app calculation. Fees and cash remain separate from premium; in-force filings are never re-rated in place.

How do errors and retries work?

Use HTTPS and JSON. Preserve request_id / x-request-id for support without logging payloads or personal data. Errors use error.code and error.message, not RFC 7807. Declines can return 200 with ok:false. Use jittered backoff for 429/transient failures, but reconcile ambiguous writes before replay: Idempotency-Key is not implemented.

What are the environment and service guarantees?

Each key resolves one licensee and sandbox or production. Use an approved dedicated sandbox licensee with synthetic data; an environment tag alone is not database isolation. The current limiter is best-effort 120/minute/key per instance, not a global quota. Agree volume, SLA, support and deprecation windows; none are promised by this public guide.

What happens after submitting the profile?

Sovereign reviews requirements; both teams agree capabilities, field mapping, identity, privacy terms, retention and acceptance tests. Approved sandbox access is issued separately. Test cross-licensee and cross-insured denial, expired keys, duplicate requests/events, payment failures and reconciliation. Readiness checks never bypass the live-bind block.

Connection responsibilities

Insured app → Partner server → Sovereign v1 → validated core
                     ↑              ↓
                     └── signed webhooks
Sovereign adapter → Provider API (licensee-specific account)

Sovereign provides its existing contracts and approved access. Partners provide architecture, identity controls, field mapping and webhook receivers, plus their own API documentation for outbound connections. Both agree privacy, consent, retention, support and acceptance criteria. Secrets stay in approved private channels.

Authentication

Issue keys in your admin under Setup → Developer API. Sandbox keys start with sae_test_, live keys with sae_live_.

curl -X POST https://sovereignautoengine.com/api/public/v1/sessions \
  -H "Authorization: Bearer sae_test_…" \
  -H "content-type: application/json" \
  -d '{}'

The licensee is resolved from the key itself — never from the request body — so a key can only ever see and write its own tenant's records. Keys are stored as a hash; the full value is shown once at creation. Keep keys on your trusted server. The x-api-key header is also supported; calls are metered and the existing limiter is best-effort per instance, not a global quota.

Quote to bind

One sequence, in order. The session id plus the bind token returned with the rate are the credentials for every step after quoting.

POST

/api/public/v1/sessionsscope: quote

{ "agency_id": null }

Opens a checkout session against the filing version effective today. Returns the filed constraints your UI should render.

POST

/api/public/v1/quotesscope: quote

{ "session_id": "…", "answers": { "zip": "37013", "vehicles": [...], "drivers": [...] } }

Rates 6- and 12-month terms, saves a quote number, and returns a session-bound bind_token used by subsequent checkout steps. Ineligible risks return reasons instead of a price.

POST

/api/public/v1/quotes/termscope: quote

{ "session_id": "…", "bind_token": "…", "term_months": 6 }

Pins the term the buyer chose. Premium is recomputed server-side from the quote's own stored input.

POST

/api/public/v1/applicationsscope: quote

{ "session_id": "…", "bind_token": "…", "quote_id": "…", "term_months": 6, "payment_plan_code": "…" }

Creates the application staging record for the selected quote and pay plan.

POST

/api/public/v1/applications/{id}/updatescope: quote

{ "session_id": "…", "bind_token": "…", "email": "…", "phone": "…" }

Applicant, driver and vehicle detail. Personally identifying values are encrypted at rest and returned masked.

POST

/api/public/v1/applications/{id}/attestationsscope: bind

{ "session_id": "…", "bind_token": "…", "accepted_codes": ["…"] }

Records the statements the buyer accepted. Required statements must all be accepted.

POST

/api/public/v1/applications/{id}/signature-stepscope: bind

{ "session_id": "…", "bind_token": "…", "inline": true }

Returns the signing step for this channel, honoring the carrier's gating rule (require before issuance, chase after, or off).

POST

/api/public/v1/applications/{id}/amount-due

{ "session_id": "…", "bind_token": "…" }

Down payment, installment amount and count — always recomputed from the saved quote, never accepted from your app.

POST

/api/public/v1/applications/{id}/bindscope: bind

{ "session_id": "…", "bind_token": "…", "method": "card", "reference": "auth code" }

Sandbox only. Issues through the normal engine; production requests return 403 payment_verification_required until a verified processor event is wired in.

Reads

GET

/api/public/v1/policiesscope: read

Recent policies for your licensee.

GET

/api/public/v1/policies/{id}scope: read

Policy header plus the masked insured profile.

GET

/api/public/v1/policies/{id}/billingscope: read

Charges, schedule, paid-to-date, balance and next due.

GET

/api/public/v1/policies/{id}/documentsscope: read

Metadata only: id, title, kind, created_at. No downloadable content or insured share URL.

GET

/api/public/v1/whoami

Confirms which licensee and environment a key resolves to.

GET

/api/public/v1/health

Unauthenticated liveness probe.

Webhooks

Subscribe an HTTPS endpoint per environment. Each delivery carries x-sovereign-timestamp and x-sovereign-signature: v1=…, an HMAC-SHA256 of {timestamp}.{body} using that endpoint's secret. Verify before you trust the body.

quote.createdA quote was rated and saved.

application.attestedThe buyer accepted the required statements.

signature.completedEvery required signature is on file.

policy.boundA policy was issued — from any channel, not just the API.

payment.postedCash was applied to a policy.

policy.cancelledA policy moved to cancelled.

claim.openedA claim opened through a supported channel; not a public FNOL endpoint.

Verify the raw body bytes, not parsed/re-serialized JSON; compare the hexadecimal signature in constant time and reject missing signatures and stale timestamps (a five-minute receiver window is recommended). Acknowledge only after durable acceptance. Failed deliveries retry through the nightly cycle, up to five attempts, and test-mode traffic is held. Delivery order is not guaranteed and there is no global event ID: agree a business-key deduplication strategy.

{ "event": "policy.bound", "created_at": "2026-10-08T12:00:00.000Z", "data": { "policy_id": "synthetic-policy-id" } }

Errors

{ "error": { "code": "insufficient_scope", "message": "…" }, "request_id": "req_…" }

401 bad key · 403 scope or account · 404 unknown record or route · 409 nothing effective to quote · 429 rate limited. Retry only 429 and transient 5xx, with backoff; reconcile ambiguous mutations before replaying them because generic idempotency keys are not implemented.

AI assistants (MCP)

Staff can connect MCP-compatible assistants (Claude, ChatGPT, Cursor and others) at https://sovereignautoengine.com/mcp. Phase 1 is read-only: policy, billing charges, document lists, quotes, claims, filing versions and the approved measure catalog. Callers sign in with OAuth as their own Sovereign user and see only what their role allows; names and contacts are masked and every call is logged. It is off by default and needs Sovereign, the licensee admin and a per-user grant to be on. There are no write tools, no free-form queries, and no API-key MCP access. The REST API above remains the integration contract for applications.

Going live

Live keys unlock only after the readiness check passes: a sandbox key that has real traffic, a quote and a bind completed through the API, a subscribed webhook endpoint, and a filing version effective today. Run it from Setup → Developer API → Go live. Certification does not remove the production bind block; processor verification and partner-specific identity/security acceptance remain prerequisites.

See the platform behind the API