{ "openapi": "3.0.3", "info": { "title": "Sovereign Foundry Core API", "version": "1.0.0", "description": "Public partner reference reviewed 2026-10-08. Existing documented subset only; variable engine responses are explicitly partial. No public FNOL, insured login, general payments, telematics or document download endpoints. Live bind blocked. No generic Idempotency-Key support. Keys stay on partner servers; consumer ownership authorization is a separate prerequisite. Internal provisioning and illustrative BOP operations are intentionally outside this handout." }, "servers": [ { "url": "https://sovereignautoengine.com/api/public/v1" } ], "paths": { "/health": { "get": { "summary": "Liveness", "operationId": "get_health", "description": "", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/whoami": { "get": { "summary": "Key licensee, environment and scopes", "operationId": "get_whoami", "description": "", "tags": [ "System" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "licensee": { "type": "object", "additionalProperties": true, "description": "Variable engine response. Inspect approved sandbox output; not a complete generated-client contract." }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sessions": { "post": { "summary": "Open a filed checkout session", "operationId": "post_sessions", "description": "Agency must belong to the key licensee. Requires online quoting and an effective filing.", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "201": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "constraints": { "type": "object", "additionalProperties": true, "description": "Variable engine response. Inspect approved sandbox output; not a complete generated-client contract." }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "quote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agency_id": { "type": "string", "format": "uuid", "nullable": true } } } } } } } }, "/quotes": { "post": { "summary": "Rate and save quote", "operationId": "post_quotes", "description": "Declines instead return HTTP 200 {ok:false,declined:true,reasons,request_id}. Success includes quote_id, quote_number, bind_token, status, six, twelve. Term rate breakdowns are variable engine output.", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "201": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineResponse" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Business decline", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "declined": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } } } } } } }, "x-required-scope": "quote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "answers": { "$ref": "#/components/schemas/RatingAnswers" } }, "required": [ "session_id", "answers" ] } } } } } }, "/quotes/term": { "post": { "summary": "Select six or twelve month term", "operationId": "post_quotes_term", "description": "", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote_id": { "type": "string", "format": "uuid" }, "term_months": { "type": "integer" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "quote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "bind_token": { "type": "string", "minLength": 20, "maxLength": 80 }, "term_months": { "type": "integer", "enum": [ 6, 12 ] } }, "required": [ "session_id", "bind_token", "term_months" ] } } } } } }, "/applications": { "post": { "summary": "Stage selected quote and payment plan", "operationId": "post_applications", "description": "", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "201": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "application_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "quote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "bind_token": { "type": "string", "minLength": 20, "maxLength": 80 }, "quote_id": { "type": "string", "format": "uuid" }, "term_months": { "type": "integer", "enum": [ 6, 12 ] }, "payment_plan_code": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "session_id", "bind_token", "quote_id", "term_months", "payment_plan_code" ] } } } } } }, "/applications/{id}": { "post": { "summary": "Read a session-owned application", "operationId": "post_applications_id", "description": "Requires API authentication and checkout credentials. No additional scope is checked on this action. Variable masked application response.", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineResponse" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCredentials" } } } } } }, "/applications/{id}/update": { "post": { "summary": "Update session-owned application", "operationId": "post_applications_id_update", "description": "Application patch includes applicant contact/address, drivers and vehicles. Filed constraints may reject details. Never log PII.", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineResponse" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "quote", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "bind_token": { "type": "string", "minLength": 20, "maxLength": 80 }, "email": { "type": "string", "maxLength": 160 }, "phone": { "type": "string", "maxLength": 20 }, "dob": { "type": "string", "maxLength": 10 }, "mailing_address1": { "type": "string", "maxLength": 120 }, "mailing_address2": { "type": "string", "maxLength": 120 }, "mailing_city": { "type": "string", "maxLength": 80 }, "mailing_state": { "type": "string", "maxLength": 2 }, "mailing_zip": { "type": "string", "maxLength": 10 }, "garaging_address1": { "type": "string", "maxLength": 120 }, "garaging_city": { "type": "string", "maxLength": 80 }, "garaging_state": { "type": "string", "maxLength": 2 }, "garaging_zip": { "type": "string", "maxLength": 10 }, "garaging_same": { "type": "boolean" }, "effective_date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "drivers": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "minimum": 0 }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "relationship": { "type": "string" }, "license_state": { "type": "string" }, "license_number": { "type": "string" }, "dob": { "type": "string" }, "sr22_required": { "type": "boolean" } }, "required": [ "seq", "first_name", "last_name" ] } }, "vehicles": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "minimum": 0 }, "year": { "type": "integer", "minimum": 1900, "maximum": 2100 }, "make": { "type": "string" }, "model": { "type": "string" }, "vin": { "type": "string" }, "lienholder_name": { "type": "string" }, "lienholder_address": { "type": "string" } }, "required": [ "seq" ] } } }, "required": [ "session_id", "bind_token" ] } } } } } }, "/applications/{id}/attestations": { "post": { "summary": "Accept required statements", "operationId": "post_applications_id_attestations", "description": "", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineResponse" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "bind", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "bind_token": { "type": "string", "minLength": 20, "maxLength": 80 }, "accepted_codes": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 40 } } }, "required": [ "session_id", "bind_token" ] } } } } } }, "/applications/{id}/signature-step": { "post": { "summary": "Resolve channel signing step", "operationId": "post_applications_id_signature_step", "description": "Variable signing/gating response; resolve required forms from this result, not hard-coded assumptions.", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineResponse" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "bind", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "bind_token": { "type": "string", "minLength": 20, "maxLength": 80 }, "inline": { "type": "boolean", "default": true } }, "required": [ "session_id", "bind_token" ] } } } } } }, "/applications/{id}/amount-due": { "post": { "summary": "Core-calculated application amount due", "operationId": "post_applications_id_amount_due", "description": "No additional scope check on this action. Session-owned application. Variable amountDueToday output, not a general policy payment endpoint.", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineResponse" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCredentials" } } } } } }, "/applications/{id}/bind": { "post": { "summary": "Sandbox bind only", "operationId": "post_applications_id_bind", "description": "SANDBOX ONLY. Production always rejects with 403 payment_verification_required. No processor token submission or live payment contract is implemented.", "tags": [ "Checkout" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "201": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineResponse" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "bind", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "bind_token": { "type": "string", "minLength": 20, "maxLength": 80 }, "method": { "type": "string", "enum": [ "card", "ach" ], "default": "card" }, "reference": { "type": "string", "maxLength": 64, "description": "Receipt/reference only; no card or bank account numbers." } }, "required": [ "session_id", "bind_token" ] } } } } } }, "/policies": { "get": { "summary": "List key-licensee recent policies", "operationId": "get_policies", "description": "Licensee-wide, not individual insured authorization. Collection headers omit agency_id and quote_id. Limit defaults 50, capped 200; no cursor.", "tags": [ "Policy reads" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyHeader" } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ] } }, "/policies/{id}": { "get": { "summary": "Read policy and partly masked profile", "operationId": "get_policies_id", "description": "UUID lookup, not policy number lookup. Server enforces key licensee, not consumer ownership.", "tags": [ "Policy reads" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/PolicyHeader" }, "profile": { "$ref": "#/components/schemas/Profile" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/policies/{id}/billing": { "get": { "summary": "Read authoritative latest-term billing", "operationId": "get_policies_id_billing", "description": "Not a processor intent, coverage guarantee or cancellation-cure calculation.", "tags": [ "Policy reads" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/policies/{id}/documents": { "get": { "summary": "Read document metadata only", "operationId": "get_policies_id_documents", "description": "Up to 100 artifacts; no download or share URLs.", "tags": [ "Policy reads" ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Success; inspect ok/declined for business outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "kind": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request or engine rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/invalid/expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, account or production bind restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or outside key licensee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No effective filing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } } }, "components": { "securitySchemes": { "BearerKey": { "type": "http", "scheme": "bearer", "description": "sae_test_* or sae_live_*; one licensee/environment; keep server-side" }, "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ] }, "CheckoutCredentials": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "bind_token": { "type": "string", "minLength": 20, "maxLength": 80 } }, "required": [ "session_id", "bind_token" ] }, "EngineResponse": { "type": "object", "additionalProperties": true, "description": "Variable engine response. Inspect approved sandbox output; not a complete generated-client contract." }, "Charge": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "amount_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "paid_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "open_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." } } }, "Schedule": { "type": "object", "properties": { "key": { "type": "string" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "label": { "type": "string" }, "premium_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "fee_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "total_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "paid_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "open_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Variable engine response. Inspect approved sandbox output; not a complete generated-client contract." } } } }, "Billing": { "type": "object", "properties": { "term": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Latest policy term, including identifiers, dates, term months, plan code, premium and fees cents." }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } }, "schedule": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } }, "balance_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "paid_cents": { "type": "integer", "description": "Integer cents, computed by Sovereign." }, "next_due": { "allOf": [ { "$ref": "#/components/schemas/Schedule" } ], "nullable": true }, "request_id": { "type": "string" } } }, "PolicyHeader": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "policy_number": { "type": "string" }, "status": { "type": "string" }, "named_insured": { "type": "string", "nullable": true }, "effective_date": { "type": "string", "format": "date", "nullable": true }, "licensee_id": { "type": "string", "format": "uuid" }, "agency_id": { "type": "string", "format": "uuid", "nullable": true }, "quote_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Profile": { "type": "object", "properties": { "insured": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email_masked": { "type": "string", "nullable": true }, "phone_masked": { "type": "string", "nullable": true }, "dob_masked": { "type": "string", "nullable": true } } }, "mailing_address": { "type": "string", "nullable": true }, "garaging_address": { "type": "string", "nullable": true }, "drivers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "relationship": { "type": "string", "nullable": true }, "dob_masked": { "type": "string", "nullable": true }, "license_masked": { "type": "string", "nullable": true }, "sr22_required": { "type": "boolean" } } } }, "vehicles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "vin_masked": { "type": "string", "nullable": true }, "lienholder_name": { "type": "string", "nullable": true } } } } } }, "RatingAnswers": { "type": "object", "properties": { "zip": { "type": "string", "pattern": "^[0-9]{5}$" }, "city": { "type": "string", "maxLength": 60 }, "county": { "type": "string", "maxLength": 60 }, "vehicles": { "type": "array", "maxItems": 8, "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1980, "maximum": 2100 }, "make": { "type": "string", "maxLength": 60 }, "model": { "type": "string", "maxLength": 80 }, "acv": { "type": "integer", "minimum": 0, "maximum": 2000000, "description": "Vehicle value in dollars, unlike response _cents fields." }, "use": { "type": "string", "enum": [ "pleasure", "commute", "business", "artisan" ], "default": "pleasure" }, "daily_miles": { "type": "integer", "minimum": 0, "maximum": 500, "default": 10 } }, "required": [ "year", "make", "model", "acv" ] } }, "drivers": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 60 }, "last_name": { "type": "string", "maxLength": 60 }, "gender": { "type": "string", "enum": [ "male", "female", "other" ] }, "marital": { "type": "string", "enum": [ "single", "married" ] }, "license_status": { "type": "string", "enum": [ "valid", "permit", "suspended", "expired", "none" ] }, "minor_violations_36m": { "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "major_violations_36m": { "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "at_fault_36m": { "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "sr22_required": { "type": "boolean", "default": false } }, "required": [ "license_status" ] } }, "coverage_level": { "type": "string", "enum": [ "basic", "standard", "full" ] }, "contact": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email", "maxLength": 160 }, "phone": { "type": "string", "maxLength": 20 } }, "required": [ "first_name", "last_name", "email", "phone" ] } } }, "Webhook": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "quote.created", "application.attested", "signature.completed", "policy.bound", "policy.cancelled", "payment.posted", "claim.opened" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "description": "Variable engine response. Inspect approved sandbox output; not a complete generated-client contract." } }, "required": [ "event", "created_at", "data" ] } } }, "x-webhook-contract": { "method": "POST", "headers": { "x-sovereign-timestamp": "Unix seconds", "x-sovereign-signature": "v1=" }, "bodySchema": "#/components/schemas/Webhook", "delivery": "Nightly retries of failures, up to 5 attempts; test outbound held. No global event id or ordering guarantee. Require signature, constant-time comparison, receiver replay window and business deduplication." }, "externalDocs": { "url": "https://sovereignautoengine.com/developers", "description": "Integration guide and partner questionnaire" } }