{ "openapi": "3.1.0", "info": { "title": "RepayIQ Partner API", "summary": "Versioned B2B API for student-loan quick quotes, repayment analysis, and document package workflows.", "description": "Production partner API surface for creating preliminary quick quotes, creating analyses, reading eligible plan options, preparing document packages, collecting supplemental official-form intake and encrypted supporting attachments, reviewing packages, generating document bundles, and downloading authorized bundle archives and prefilled official forms.", "version": "1.36.0" }, "servers": [ { "url": "/", "description": "Current RepayIQ deployment" } ], "security": [ { "RepayIQPartnerId": [], "RepayIQApiKey": [] } ], "tags": [ { "name": "Quick Quotes", "description": "Estimate potential repayment-plan matches without creating a saved analysis or submitting loan records." }, { "name": "Analyses", "description": "Create and read repayment analyses." }, { "name": "Document Packages", "description": "Prepare, review, and bundle repayment program documents." } ], "paths": { "/api/v1/quick-quotes": { "post": { "operationId": "createPartnerQuickQuote", "tags": [ "Quick Quotes" ], "summary": "Create a preliminary repayment quote", "description": "Evaluates loose borrower and estimated loan inputs against the server-side repayment rules and calculation engine. The response is not persisted and cannot be used for document preparation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickQuoteRequest" }, "examples": { "estimatedDirectDebt": { "summary": "Estimated Direct undergraduate debt", "value": { "analysis_as_of": "2026-07-19", "annual_income_cents": 6000000, "estimated_balance_cents": 4500000, "family_size": 2, "state_of_residence": "CA", "loan_category": "direct_undergraduate", "loan_timing": "before_2026_07_01" } } } } } }, "responses": { "200": { "description": "Preliminary plan matches and representative-rate assumptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickQuoteEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses": { "post": { "operationId": "createPartnerAnalysis", "tags": [ "Analyses" ], "summary": "Create a partner analysis", "description": "Evaluates borrower and loan data, returning repayment quotes, eligibility decisions, recommendation data, and workflow plan options.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnalysisRequest" }, "examples": { "studentAidTextExport": { "summary": "StudentAid text export", "value": { "borrower_profile": { "analysis_as_of": "2026-07-10", "state_of_residence": "CA", "poverty_guideline_region": "contiguous_48_dc", "marital_status": "single", "tax_filing_status": "single", "spouse_income_included": false, "adjusted_gross_income_cents": 7200000, "family_size": 1, "dependent_count": 0, "direct_loan_repayment_start_status": "on_or_after_2006_07_01", "extended_new_borrower_status": "new_borrower", "ffel_extended_new_borrower_status": "new_borrower", "ffel_income_sensitive_expected_monthly_gross_income_cents": 600000, "ibr_new_borrower_status": "not_new_borrower", "repaye_qualifying_payment_count_since_2024_07_01": 0, "parent_plus_consolidation_idr_payment_status": "unknown", "paye_new_borrower_status": "unknown", "paye_enrollment_status": "not_repaying_on_2024_07_01", "icr_enrollment_status": "not_repaying_on_2024_07_01", "icr_joint_repayment_with_spouse": false }, "raw_text": "Loan export text...", "source_label": "studentaid_text_export", "include_rule_traces": false, "include_calculation_traces": false } } } } } }, "responses": { "200": { "description": "Analysis created or returned from an idempotent retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}": { "get": { "operationId": "getPartnerAnalysis", "tags": [ "Analyses" ], "summary": "Get an analysis", "description": "Reads the immutable analysis snapshot plus the current derived workflow summary.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" } ], "responses": { "200": { "description": "Analysis snapshot and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/plan-options": { "get": { "operationId": "getPartnerPlanOptions", "tags": [ "Analyses" ], "summary": "Get selectable plan options", "description": "Returns the API-safe plan-selection surface and current workflow state.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" } ], "responses": { "200": { "description": "Plan options and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanOptionsEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages": { "post": { "operationId": "createPartnerDocumentPackage", "tags": [ "Document Packages" ], "summary": "Create a document package", "description": "Starts document preparation from a selectable plan option.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentPackageRequest" } } } }, "responses": { "200": { "description": "Document package and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPackageEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/supplemental-intake": { "get": { "operationId": "getPartnerSupplementalIntake", "tags": [ "Document Packages" ], "summary": "Get supplemental intake status", "description": "Returns redacted source-scoped supplemental intake status. Direct Alternative packages expose an optional encrypted guidance intake whose narrative values are never returned.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" }, { "name": "source_id", "in": "query", "required": false, "description": "Supplemental intake source to return. Defaults to the package's first available source.", "schema": { "type": "string", "enum": [ "income_driven_repayment_plan_request_pdf", "direct_consolidation_application_pdf", "direct_consolidation_add_loans_pdf", "repayment_plan_request_pdf", "pslf_tepslf_certification_application_pdf", "teacher_loan_forgiveness_application_pdf", "total_and_permanent_disability_discharge_pdf", "school_related_discharge_workflow", "general_forbearance_pdf", "economic_hardship_deferment_pdf", "unemployment_deferment_pdf", "student_loan_debt_burden_forbearance_pdf", "in_school_deferment_pdf", "parent_plus_borrower_deferment_pdf", "graduate_fellowship_deferment_pdf", "rehabilitation_training_deferment_pdf", "cancer_treatment_deferment_pdf", "military_service_and_post_active_duty_deferment_pdf", "medical_dental_national_guard_dod_forbearance_pdf", "loan_rehabilitation_income_and_expense_pdf", "loan_reaffirmation_form", "federal_tax_information_consent_revocation_form", "direct_alternative_repayment_guidance", "ffel_repayment_plan_holder_guidance" ] } } ], "responses": { "200": { "description": "Redacted supplemental intake status and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementalIntakeEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "upsertPartnerSupplementalIntake", "tags": [ "Document Packages" ], "summary": "Save supplemental intake", "description": "Saves intake for one source. Direct Alternative accepts optional private request notes under direct_alternative_repayment_guidance. FFEL repayment packages accept repeatable request and holder-decision records under ffel_repayment_plan_holder_guidance. All raw values are encrypted before persistence; API reads return redacted field status plus a sanitized FFEL holder summary that never exposes confirmation-reference values.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertSupplementalIntakeRequest" } } } }, "responses": { "200": { "description": "Redacted supplemental intake status and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplementalIntakeEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/attachments": { "get": { "operationId": "listPartnerOfficialFormAttachments", "tags": [ "Document Packages" ], "summary": "List supporting attachments", "description": "Returns public-safe attachment metadata, the branch-derived attachment manifest, and the current workflow. Storage keys and file contents are never included.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" }, { "name": "source_id", "in": "query", "required": false, "description": "Attachment manifest source. Pass direct_alternative_repayment_guidance for optional evidence requested by a servicer or federal reviewer, or ffel_repayment_plan_holder_guidance for optional income records requested by a FFEL holder.", "schema": { "type": "string", "enum": [ "income_driven_repayment_plan_request_pdf", "total_and_permanent_disability_discharge_pdf", "school_related_discharge_workflow", "general_forbearance_pdf", "economic_hardship_deferment_pdf", "unemployment_deferment_pdf", "student_loan_debt_burden_forbearance_pdf", "in_school_deferment_pdf", "parent_plus_borrower_deferment_pdf", "graduate_fellowship_deferment_pdf", "rehabilitation_training_deferment_pdf", "cancer_treatment_deferment_pdf", "military_service_and_post_active_duty_deferment_pdf", "medical_dental_national_guard_dod_forbearance_pdf", "loan_rehabilitation_income_and_expense_pdf", "direct_alternative_repayment_guidance", "ffel_repayment_plan_holder_guidance" ], "default": "income_driven_repayment_plan_request_pdf" } } ], "responses": { "200": { "description": "Attachment manifest and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentCollectionEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "uploadPartnerOfficialFormAttachment", "tags": [ "Document Packages" ], "summary": "Upload a supporting attachment", "description": "Uploads one PDF, JPEG, or PNG up to 10 MiB. RepayIQ verifies the file signature, encrypts the bytes before private storage, and stores public-safe metadata separately.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadOfficialFormAttachmentRequest" } } } }, "responses": { "201": { "description": "Verified attachment metadata, updated manifest, and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentCollectionEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/UnprocessableEntity" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/attachments/{attachment_id}": { "delete": { "operationId": "deletePartnerOfficialFormAttachment", "tags": [ "Document Packages" ], "summary": "Delete a supporting attachment", "description": "Marks attachment metadata deleted, removes the encrypted private object, and returns the updated manifest and workflow.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" }, { "$ref": "#/components/parameters/AttachmentId" } ], "responses": { "200": { "description": "Updated attachment manifest and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentCollectionEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/attachments/{attachment_id}/content": { "get": { "operationId": "downloadPartnerOfficialFormAttachment", "tags": [ "Document Packages" ], "summary": "Download a supporting attachment", "description": "Decrypts and integrity-checks the private object server-side, then streams it as a no-store attachment response.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" }, { "$ref": "#/components/parameters/AttachmentId" } ], "responses": { "200": { "description": "Original attachment bytes after decryption and integrity validation.", "headers": { "Content-Disposition": { "schema": { "type": "string" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/review": { "post": { "operationId": "reviewPartnerDocumentPackage", "tags": [ "Document Packages" ], "summary": "Review a document package", "description": "Marks required package fields as reviewed before bundle generation.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewDocumentPackageRequest" } } } }, "responses": { "200": { "description": "Updated document package and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPackageEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/bundle": { "post": { "operationId": "createPartnerDocumentBundle", "tags": [ "Document Packages" ], "summary": "Generate a document bundle", "description": "Generates server-owned document bundle metadata and returns a protected ZIP download URL after the workflow reaches ready_to_generate_bundle.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentBundleRequest" } } } }, "responses": { "200": { "description": "Document bundle and workflow summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentBundleEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/bundle/content": { "get": { "operationId": "downloadPartnerDocumentBundleArchive", "tags": [ "Document Packages" ], "summary": "Download a document bundle archive", "description": "Generates an authorized ZIP containing bundle artifacts, integrity-checked supporting documents, and any prefilled official forms available for the selected plan. Official forms in the archive still require the borrower's handwritten signature.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" } ], "responses": { "200": { "description": "Document bundle ZIP with private, no-store response headers and an integrity digest.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The archive source payload exceeds the configured size or entry limit." }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/analyses/{analysis_id}/document-packages/{document_package_id}/official-forms/{source_id}/content": { "get": { "operationId": "downloadPartnerOfficialForm", "tags": [ "Document Packages" ], "summary": "Download a prefilled official form instance", "description": "Generates one hash-verified official PDF represented by the ready document bundle. Supported outputs include the IDR request, Direct Consolidation application, Request to Add Loans (with appended continuation pages when required), fixed Repayment Plan Request, and one PSLF form per employment period. Borrower signature fields remain blank; PSLF employer certification and signature fields also remain blank for the authorized employer official.", "parameters": [ { "$ref": "#/components/parameters/AnalysisId" }, { "$ref": "#/components/parameters/DocumentPackageId" }, { "$ref": "#/components/parameters/SourceId" }, { "$ref": "#/components/parameters/FormInstanceId" } ], "responses": { "200": { "description": "Prefilled official form PDF with private, no-store response headers.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "RepayIQPartnerId": { "type": "apiKey", "in": "header", "name": "x-repayiq-partner-id", "description": "Partner identifier assigned by RepayIQ." }, "RepayIQApiKey": { "type": "apiKey", "in": "header", "name": "x-repayiq-api-key", "description": "Raw partner API key. RepayIQ stores only a SHA-256 hash server-side." } }, "parameters": { "AnalysisId": { "name": "analysis_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "DocumentPackageId": { "name": "document_package_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "AttachmentId": { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "SourceId": { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "income_driven_repayment_plan_request_pdf", "direct_consolidation_application_pdf", "direct_consolidation_add_loans_pdf", "repayment_plan_request_pdf", "pslf_tepslf_certification_application_pdf", "teacher_loan_forgiveness_application_pdf", "teacher_loan_forgiveness_forbearance_pdf", "total_and_permanent_disability_discharge_pdf", "total_and_permanent_disability_representative_designation_pdf", "closed_school_discharge_pdf", "unpaid_refund_discharge_pdf", "false_certification_disqualifying_status_pdf", "false_certification_high_school_status_pdf", "false_certification_identity_theft_pdf", "false_certification_unauthorized_signature_pdf", "forgery_discharge_pdf", "general_forbearance_pdf", "economic_hardship_deferment_pdf", "unemployment_deferment_pdf", "student_loan_debt_burden_forbearance_pdf", "in_school_deferment_pdf", "parent_plus_borrower_deferment_pdf", "graduate_fellowship_deferment_pdf", "rehabilitation_training_deferment_pdf", "cancer_treatment_deferment_pdf", "military_service_and_post_active_duty_deferment_pdf", "medical_dental_national_guard_dod_forbearance_pdf", "loan_rehabilitation_income_and_expense_pdf", "loan_reaffirmation_form", "federal_tax_information_consent_revocation_form" ] } }, "FormInstanceId": { "name": "form_instance_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Stable form instance returned in official_forms metadata. Required when one source produces multiple PDFs, including one PSLF form per employment period, one Teacher Loan Forgiveness form per eligible loan holder or servicer, TPD application or representative instances, and holder-specific deferment or forbearance requests." }, "IdempotencyKey": { "name": "idempotency-key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Optional key for safely retrying analysis creation." } }, "responses": { "Unauthorized": { "description": "Missing or invalid partner credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "The requested analysis or document package is not available to the authenticated partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Conflict": { "description": "The idempotency key conflicts with a different request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UnprocessableEntity": { "description": "Validation or workflow error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Partner rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Limit": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "QuickQuoteRequest": { "type": "object", "required": [ "annual_income_cents", "estimated_balance_cents", "family_size", "state_of_residence", "loan_category", "loan_timing" ], "properties": { "analysis_as_of": { "type": "string", "format": "date", "description": "Defaults to the server date and must be on or after July 1, 2026." }, "annual_income_cents": { "type": "integer", "minimum": 0, "maximum": 10000000000 }, "estimated_balance_cents": { "type": "integer", "minimum": 1, "maximum": 10000000000 }, "family_size": { "type": "integer", "minimum": 1, "maximum": 50 }, "state_of_residence": { "type": "string", "minLength": 2, "maxLength": 2 }, "loan_category": { "type": "string", "enum": [ "direct_undergraduate", "direct_graduate", "direct_parent_plus", "ffel_stafford", "mixed_or_not_sure" ] }, "loan_timing": { "type": "string", "enum": [ "before_2026_07_01", "on_or_after_2026_07_01", "not_sure" ] } }, "additionalProperties": false }, "QuickQuoteOption": { "type": "object", "required": [ "plan_id", "plan_label", "eligibility_status", "quote_status", "notes" ], "properties": { "plan_id": { "type": "string" }, "plan_label": { "type": "string" }, "eligibility_status": { "type": "string", "enum": [ "potential_match", "needs_more_information" ] }, "quote_status": { "type": "string", "enum": [ "calculated", "requires_input", "unsupported" ] }, "estimated_monthly_payment_cents": { "type": "integer", "minimum": 0 }, "estimated_total_paid_cents": { "type": "integer", "minimum": 0 }, "payoff_month_count": { "type": "integer", "minimum": 0 }, "forgiveness_month_count": { "type": "integer", "minimum": 0 }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "QuickQuoteAssumptions": { "type": "object", "required": [ "assumption_version", "requested_loan_category", "resolved_loan_category", "requested_loan_timing", "resolved_loan_timing", "estimated_balance_cents", "annual_income_cents", "family_size", "state_of_residence", "assumed_interest_rate_bps", "interest_rate_source_label", "interest_rate_source_url", "balance_treated_as_principal" ], "properties": { "assumption_version": { "const": "2026.07.19.1" }, "requested_loan_category": { "type": "string", "enum": [ "direct_undergraduate", "direct_graduate", "direct_parent_plus", "ffel_stafford", "mixed_or_not_sure" ] }, "resolved_loan_category": { "type": "string", "enum": [ "direct_undergraduate", "direct_graduate", "direct_parent_plus", "ffel_stafford" ] }, "requested_loan_timing": { "type": "string", "enum": [ "before_2026_07_01", "on_or_after_2026_07_01", "not_sure" ] }, "resolved_loan_timing": { "type": "string", "enum": [ "before_2026_07_01", "on_or_after_2026_07_01" ] }, "estimated_balance_cents": { "type": "integer", "minimum": 1 }, "annual_income_cents": { "type": "integer", "minimum": 0 }, "family_size": { "type": "integer", "minimum": 1 }, "state_of_residence": { "type": "string" }, "assumed_interest_rate_bps": { "type": "number", "minimum": 0, "description": "Representative rate on the assumed loan, not a repayment-plan rate." }, "interest_rate_source_label": { "type": "string" }, "interest_rate_source_url": { "type": "string", "format": "uri" }, "balance_treated_as_principal": { "const": true } }, "additionalProperties": false }, "QuickQuoteResponse": { "type": "object", "required": [ "quote_version", "quote_id", "generated_at", "analysis_as_of", "confidence", "preliminary", "potential_match_count", "options", "assumptions", "warnings", "next_step" ], "properties": { "quote_version": { "const": "0.1.0" }, "quote_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "analysis_as_of": { "type": "string", "format": "date" }, "confidence": { "type": "string", "enum": [ "medium", "low" ] }, "preliminary": { "const": true }, "potential_match_count": { "type": "integer", "minimum": 0 }, "lowest_estimated_payment_plan_id": { "type": "string", "description": "The lowest monthly amount among calculated options shown, not a recommendation." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/QuickQuoteOption" } }, "assumptions": { "$ref": "#/components/schemas/QuickQuoteAssumptions" }, "warnings": { "type": "array", "items": { "type": "string" } }, "next_step": { "type": "object", "required": [ "full_analysis_required" ], "properties": { "full_analysis_required": { "const": true } }, "additionalProperties": false } }, "additionalProperties": false }, "QuickQuoteEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/QuickQuoteResponse" }, "error_message": { "const": "" } } } ] }, "ApiEnvelope": { "type": "object", "required": [ "success", "data", "error_message" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object" }, "error_message": { "type": "string", "description": "Empty on success. On failure, one or more lines prefixed with \"- \"." } }, "additionalProperties": false }, "ErrorEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "success": { "const": false }, "data": { "type": "object", "additionalProperties": true } } } ] }, "CreateAnalysisRequest": { "type": "object", "required": [ "borrower_profile" ], "oneOf": [ { "required": [ "raw_text" ] }, { "required": [ "portfolio" ] } ], "properties": { "borrower_profile": { "$ref": "#/components/schemas/BorrowerProfile" }, "consolidation_scenario": { "$ref": "#/components/schemas/ConsolidationScenarioRequest" }, "document_screening": { "$ref": "#/components/schemas/DocumentScreening" }, "raw_text": { "type": "string", "minLength": 1, "description": "Raw text from a supported student-loan export." }, "portfolio": { "$ref": "#/components/schemas/NormalizedLoanPortfolio" }, "source_label": { "type": "string", "enum": [ "studentaid_text_export", "servicer_text_export", "manual_text" ], "default": "studentaid_text_export" }, "include_rule_traces": { "type": "boolean", "default": false }, "include_calculation_traces": { "type": "boolean", "default": false } }, "additionalProperties": false }, "ConsolidationScenarioRequest": { "type": "object", "description": "Requests a saved new-Direct-Consolidation what-if alongside the current-portfolio analysis.", "properties": { "selection_mode": { "type": "string", "enum": [ "all_eligible", "selected_loans" ], "default": "all_eligible" }, "included_loan_ids": { "type": "array", "description": "Required and non-empty when selection_mode is selected_loans. IDs must exist in the submitted portfolio.", "items": { "type": "string", "minLength": 1 }, "default": [] } }, "additionalProperties": false }, "ConsolidationComparison": { "type": "object", "required": [ "scenario_id", "scenario_type", "status", "included_loan_ids", "excluded_loans", "plan_quotes", "source_ids", "warnings" ], "properties": { "scenario_id": { "type": "string" }, "scenario_type": { "const": "new_direct_consolidation" }, "status": { "type": "string", "enum": [ "available", "requires_input", "not_available" ] }, "selection_mode": { "type": "string", "enum": [ "all_eligible", "selected_loans" ] }, "included_loan_ids": { "type": "array", "items": { "type": "string" } }, "excluded_loans": { "type": "array", "items": { "type": "object", "required": [ "loan_id", "reason", "message" ], "properties": { "loan_id": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_selected", "unsupported_loan_type", "loan_status_not_eligible", "default_resolution_required" ] }, "message": { "type": "string" } }, "additionalProperties": false } }, "projected_consolidation_loan": { "type": "object", "additionalProperties": true }, "projected_portfolio": { "$ref": "#/components/schemas/NormalizedLoanPortfolio" }, "interest_rate_calculation": { "type": "object", "properties": { "weight_basis": { "const": "outstanding_balance_including_accrued_interest" }, "weighted_average_interest_rate_bps": { "type": "number", "minimum": 0 }, "rounded_interest_rate_bps": { "type": "number", "minimum": 0 }, "rounding_increment_bps": { "const": 12.5 }, "projected_principal_balance_cents": { "type": "integer", "minimum": 0 }, "capitalized_interest_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "plan_quotes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recommendation": { "type": "object", "additionalProperties": true }, "source_ids": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "BorrowerProfile": { "type": "object", "required": [ "analysis_as_of", "state_of_residence", "poverty_guideline_region", "marital_status", "tax_filing_status", "spouse_income_included", "adjusted_gross_income_cents", "family_size", "dependent_count" ], "properties": { "borrower_id": { "type": "string" }, "analysis_as_of": { "type": "string", "format": "date" }, "state_of_residence": { "type": "string", "minLength": 2 }, "poverty_guideline_region": { "type": "string", "enum": [ "contiguous_48_dc", "alaska", "hawaii" ] }, "marital_status": { "type": "string", "enum": [ "single", "married", "separated", "unknown" ] }, "tax_filing_status": { "type": "string", "enum": [ "single", "married_filing_jointly", "married_filing_separately", "head_of_household", "qualifying_surviving_spouse", "unknown" ] }, "spouse_income_included": { "type": "boolean" }, "adjusted_gross_income_cents": { "type": "integer", "minimum": 0 }, "spouse_adjusted_gross_income_cents": { "type": "integer", "minimum": 0 }, "alternative_taxable_income_cents": { "type": "integer", "minimum": 0 }, "family_size": { "type": "integer", "minimum": 1 }, "dependent_count": { "type": "integer", "minimum": 0 }, "direct_loan_repayment_start_status": { "type": "string", "description": "Whether the borrower first entered Direct Loan repayment before July 1, 2006. This selects the applicable Graduated and Extended term rules.", "enum": [ "before_2006_07_01", "on_or_after_2006_07_01", "unknown" ] }, "extended_new_borrower_status": { "type": "string", "description": "Whether the borrower meets the Extended-plan new-borrower test based on having no outstanding Direct Loan balance on October 7, 1998 or when obtaining a Direct Loan after that date.", "enum": [ "new_borrower", "not_new_borrower", "unknown" ] }, "ffel_extended_new_borrower_status": { "type": "string", "description": "Whether the borrower meets the FFEL Extended-plan new-borrower test based on having no outstanding FFEL balance on October 7, 1998 or when obtaining an FFEL loan after that date.", "enum": [ "new_borrower", "not_new_borrower", "unknown" ] }, "ffel_income_sensitive_expected_monthly_gross_income_cents": { "type": "integer", "description": "Expected total monthly gross income supplied to the FFEL holder for its lender-specific Income-Sensitive repayment schedule.", "minimum": 0 }, "ibr_new_borrower_status": { "type": "string", "description": "Federal IBR new-borrower category used to select the 10 percent or 15 percent formula.", "enum": [ "new_borrower", "not_new_borrower", "unknown" ] }, "repaye_qualifying_payment_count_since_2024_07_01": { "type": "integer", "description": "Qualifying REPAYE payments made on or after July 1, 2024. Required to confirm Direct IBR eligibility.", "minimum": 0 }, "spouse_eligible_loan_debt_cents": { "type": "integer", "description": "Spouse outstanding principal and interest on eligible federal loans. Required for Direct IBR or PAYE when spouse income is included and for joint ICR repayment.", "minimum": 0 }, "ibr_standard_payment_cap_cents": { "type": "integer", "description": "Historical 10-year standard payment cap from borrower account history when the borrower is already repaying under IBR.", "minimum": 1 }, "parent_plus_consolidation_idr_payment_status": { "type": "string", "description": "Whether every outstanding Direct Consolidation Loan with Parent PLUS history has at least one confirmed ICR, PAYE, or IBR payment made on or after July 4, 2025 for the temporary excepted-consolidation transition rule.", "enum": [ "all_qualifying_payments_confirmed", "not_all_qualifying_payments_confirmed", "unknown" ] }, "paye_new_borrower_status": { "type": "string", "description": "Whether the borrower meets both PAYE new-borrower tests involving October 1, 2007 loan-balance history and a qualifying Direct Loan disbursement on or after October 1, 2011.", "enum": [ "new_borrower", "not_new_borrower", "unknown" ] }, "paye_enrollment_status": { "type": "string", "description": "PAYE enrollment history used to confirm enrollment on July 1, 2024 and that the borrower did not subsequently leave the plan.", "enum": [ "current_or_associated_forbearance", "left_after_2024_07_01", "not_repaying_on_2024_07_01", "unknown" ] }, "paye_standard_payment_cap_cents": { "type": "integer", "description": "Historical 10-year standard payment cap based on eligible loan balances and rates when the borrower entered PAYE.", "minimum": 1 }, "icr_enrollment_status": { "type": "string", "description": "ICR enrollment history used to preserve existing enrollment or identify a borrower who left ICR after July 1, 2024.", "enum": [ "current_or_associated_forbearance", "left_after_2024_07_01", "not_repaying_on_2024_07_01", "unknown" ] }, "icr_joint_repayment_with_spouse": { "type": "boolean", "description": "Whether both spouses elect to repay their eligible Direct Loans jointly under ICR." }, "icr_12_year_standard_payment_cents": { "type": "integer", "description": "Historical 12-year standard payment from borrower account history when the borrower is already repaying under ICR.", "minimum": 1 }, "spouse_icr_12_year_standard_payment_cents": { "type": "integer", "description": "Spouse 12-year standard payment used with spouse income, eligible debt, and joint ICR election.", "minimum": 1 }, "public_service_employment": { "$ref": "#/components/schemas/PublicServiceEmployment" } }, "additionalProperties": false }, "PublicServiceEmployment": { "type": "object", "required": [ "qualifying_employer_claimed", "full_time_claimed" ], "properties": { "employer_name": { "type": "string" }, "employer_ein": { "type": "string" }, "qualifying_employer_claimed": { "type": "boolean" }, "full_time_claimed": { "type": "boolean" }, "average_hours_per_week": { "type": "number", "minimum": 0 }, "service_start_date": { "type": "string", "format": "date" }, "service_end_date": { "type": "string", "format": "date" }, "certified_payment_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "DocumentScreening": { "type": "object", "description": "Optional high-level screening used to identify possible document paths. Answers do not determine program eligibility.", "properties": { "public_service_employment": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "qualifying_teaching_service": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "total_and_permanent_disability": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "school_related_discharge_issue": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "current_education_or_training": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "parent_plus_student_enrollment": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "economic_hardship_deferment": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "unemployment_deferment": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "unemployment_or_economic_hardship": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "serious_illness_or_cancer_treatment": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "military_service_or_post_active_duty": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "military_or_national_service": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "federal_loan_default": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "inadvertent_overborrowing": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "federal_tax_information_consent_revocation": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "joint_consolidation_or_loan_limit_issue": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "temporary_payment_relief": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "graduate_fellowship_participation": { "$ref": "#/components/schemas/DocumentScreeningAnswer" }, "rehabilitation_training_participation": { "$ref": "#/components/schemas/DocumentScreeningAnswer" } }, "additionalProperties": false }, "DocumentScreeningAnswer": { "type": "string", "enum": [ "yes", "no", "unsure", "not_answered" ] }, "NormalizedLoanPortfolio": { "type": "object", "description": "Normalized loan portfolio accepted in place of raw_text for trusted integrations.", "additionalProperties": true }, "DocumentLoanSelection": { "type": "object", "description": "Borrower-confirmed consolidation intent. Loan IDs must belong to the immutable analysis portfolio and may appear in only one selection array. For a new Direct Consolidation Loan made on or after July 1, 2026, selected_plan_id must be tiered_standard or rap. A new consolidation that repays Parent PLUS debt cannot use rap.", "required": [ "mode" ], "properties": { "selection_version": { "type": "string", "enum": [ "0.1.0" ], "default": "0.1.0" }, "mode": { "type": "string", "enum": [ "not_pursuing", "new_consolidation", "add_to_existing" ] }, "consolidation_included_loan_ids": { "type": "array", "description": "Loans listed in the new consolidation application's loans-to-consolidate section.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "consolidation_excluded_loan_ids": { "type": "array", "description": "Loans listed in the new consolidation application's loans-not-being-consolidated section.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "loans_to_add_ids": { "type": "array", "description": "Loans listed on a Request to Add Loans for an existing Direct Consolidation Loan.", "items": { "type": "string", "minLength": 1 }, "default": [] } }, "additionalProperties": false }, "CreateDocumentPackageRequest": { "type": "object", "properties": { "analysis_scenario_id": { "type": "string", "minLength": 1, "description": "Pass the scenario_id returned by consolidation_comparison or workflow.plan_options when selecting a scenario-specific plan. The server derives the matching immutable loan selection." }, "selected_plan_id": { "type": "string", "minLength": 1, "description": "A plan_id returned by workflow.plan_options. Current plan IDs include direct_standard, direct_graduated, direct_extended_fixed, direct_extended_graduated, and direct_alternative for eligible pre-cutoff Direct debt; tiered_standard for post-cutoff Direct debt; direct_ibr, paye, icr, rap, ffel_standard, ffel_graduated, ffel_income_sensitive, ffel_extended_fixed, ffel_extended_graduated, ffel_ibr, and perkins_institution. direct_alternative is selectable only for a review-required federal approval handoff and has no calculated payment before written approval. repaye_save is not selectable." }, "include_analysis_summary": { "type": "boolean", "default": true }, "document_loan_selection": { "$ref": "#/components/schemas/DocumentLoanSelection" } }, "additionalProperties": false }, "UpsertSupplementalIntakeRequest": { "type": "object", "required": [ "fields" ], "properties": { "source_id": { "type": "string", "enum": [ "income_driven_repayment_plan_request_pdf", "direct_consolidation_application_pdf", "direct_consolidation_add_loans_pdf", "repayment_plan_request_pdf", "pslf_tepslf_certification_application_pdf", "teacher_loan_forgiveness_application_pdf", "total_and_permanent_disability_discharge_pdf", "school_related_discharge_workflow", "general_forbearance_pdf", "economic_hardship_deferment_pdf", "unemployment_deferment_pdf", "student_loan_debt_burden_forbearance_pdf", "in_school_deferment_pdf", "parent_plus_borrower_deferment_pdf", "graduate_fellowship_deferment_pdf", "rehabilitation_training_deferment_pdf", "cancer_treatment_deferment_pdf", "military_service_and_post_active_duty_deferment_pdf", "medical_dental_national_guard_dod_forbearance_pdf", "loan_rehabilitation_income_and_expense_pdf", "loan_reaffirmation_form", "federal_tax_information_consent_revocation_form", "direct_alternative_repayment_guidance", "ffel_repayment_plan_holder_guidance" ], "description": "Optional when the package has one source. Required to target a non-primary source in a multi-form package. Guidance sources accept request-tracking values and never represent an official federal form." }, "fields": { "type": "object", "description": "Source-scoped values keyed by supplemental field ID. Official-form sources accept only mapped fields and enforce their branch, capacity, signer, loan, and attachment rules. direct_alternative_repayment_guidance accepts its four documented optional fields. ffel_repayment_plan_holder_guidance accepts ffel_current_payment_acknowledged plus repeatable ffel_holder__N__request_method, request_status, submitted_on, decision_status, decision_received_on, approved_plan_id, approved_monthly_payment_cents, approved_payment_effective_on, annual_review_due_on, income_evidence_status, and confirmation_reference fields. N must match a parsed active FFEL holder. Holder confirmation references are limited to 160 characters and are never returned or generated.", "additionalProperties": { "type": [ "string", "boolean", "null" ] } } }, "additionalProperties": false }, "UploadOfficialFormAttachmentRequest": { "type": "object", "required": [ "document_role", "file" ], "properties": { "source_id": { "type": "string", "enum": [ "income_driven_repayment_plan_request_pdf", "total_and_permanent_disability_discharge_pdf", "school_related_discharge_workflow", "general_forbearance_pdf", "economic_hardship_deferment_pdf", "unemployment_deferment_pdf", "student_loan_debt_burden_forbearance_pdf", "in_school_deferment_pdf", "parent_plus_borrower_deferment_pdf", "graduate_fellowship_deferment_pdf", "rehabilitation_training_deferment_pdf", "cancer_treatment_deferment_pdf", "military_service_and_post_active_duty_deferment_pdf", "medical_dental_national_guard_dod_forbearance_pdf", "loan_rehabilitation_income_and_expense_pdf", "direct_alternative_repayment_guidance", "ffel_repayment_plan_holder_guidance" ], "default": "income_driven_repayment_plan_request_pdf" }, "document_role": { "$ref": "#/components/schemas/OfficialFormAttachmentDocumentRole" }, "file": { "type": "string", "format": "binary", "description": "One application/pdf, image/jpeg, or image/png file no larger than 10 MiB." } }, "additionalProperties": false }, "ReviewDocumentPackageRequest": { "type": "object", "properties": { "reviewed_field_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "default": [] } }, "additionalProperties": false }, "CreateDocumentBundleRequest": { "type": "object", "additionalProperties": false }, "AnalysisEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AnalysisData" } } } ] }, "PlanOptionsEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlanOptionsData" } } } ] }, "DocumentPackageEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentPackageData" } } } ] }, "SupplementalIntakeEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupplementalIntakeData" } } } ] }, "AttachmentCollectionEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AttachmentCollectionData" } } } ] }, "DocumentBundleEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentBundleData" } } } ] }, "AnalysisData": { "type": "object", "required": [ "analysis_id", "channel", "workflow" ], "properties": { "analysis_id": { "type": "string" }, "snapshot_version": { "type": "string" }, "channel": { "type": "string", "enum": [ "b2b" ] }, "document_screening": { "$ref": "#/components/schemas/DocumentScreening" }, "partner_id": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "portfolio": { "$ref": "#/components/schemas/NormalizedLoanPortfolio" }, "eligibility_decisions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "formula_bindings": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "plan_quotes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recommendation": { "type": "object", "additionalProperties": true }, "consolidation_comparison": { "$ref": "#/components/schemas/ConsolidationComparison" }, "trace": { "type": "object", "additionalProperties": true }, "warnings": { "type": "array", "items": { "type": "string" } }, "workflow": { "$ref": "#/components/schemas/AnalysisWorkflowSummary" } }, "additionalProperties": true }, "PlanOptionsData": { "type": "object", "required": [ "plan_options", "workflow" ], "properties": { "plan_options": { "type": "array", "items": { "$ref": "#/components/schemas/RepaymentWorkflowPlanOption" } }, "workflow": { "$ref": "#/components/schemas/AnalysisWorkflowSummary" } }, "additionalProperties": false }, "DocumentPackageData": { "type": "object", "required": [ "document_package", "workflow" ], "properties": { "document_package": { "$ref": "#/components/schemas/DocumentPackage" }, "workflow": { "$ref": "#/components/schemas/AnalysisWorkflowSummary" } }, "additionalProperties": false }, "SupplementalIntakeData": { "type": "object", "required": [ "official_form_readiness_report", "supplemental_intake", "supplemental_intakes", "workflow" ], "properties": { "ffel_holder_repayment": { "$ref": "#/components/schemas/FfelHolderRepaymentWorkflowSummary" }, "official_form_readiness_report": { "type": "object", "additionalProperties": true }, "supplemental_intake": { "type": [ "object", "null" ], "additionalProperties": true }, "supplemental_intakes": { "type": "array", "description": "Redacted status records for every saved supplemental intake source available to the document package.", "items": { "type": "object", "additionalProperties": true } }, "workflow": { "$ref": "#/components/schemas/AnalysisWorkflowSummary" } }, "additionalProperties": false }, "FfelHolderRepaymentWorkflowSummary": { "type": "object", "description": "Sanitized FFEL holder workflow data. Portfolio identity fields are server-derived; request and decision values are borrower- or partner-reported holder outcomes, not RepayIQ calculations or approvals.", "required": [ "summary_version", "source_id", "selected_plan_id", "current_payment_acknowledged", "holder_count", "holders", "notes" ], "properties": { "summary_version": { "type": "string" }, "source_id": { "type": "string", "const": "ffel_repayment_plan_holder_guidance" }, "selected_plan_id": { "type": "string" }, "current_payment_acknowledged": { "type": "boolean" }, "holder_count": { "type": "integer", "minimum": 0 }, "holders": { "type": "array", "items": { "$ref": "#/components/schemas/FfelHolderRepaymentRecordSummary" } }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "FfelHolderRepaymentRecordSummary": { "type": "object", "required": [ "holder_record_number", "holder_label", "loan_count", "outstanding_balance_cents", "request_method", "request_status", "submitted_on", "decision_status", "decision_received_on", "approved_plan_id", "approved_monthly_payment_cents", "approved_payment_effective_on", "annual_review_due_on", "income_evidence_status", "confirmation_reference_present", "saved_field_count" ], "properties": { "holder_record_number": { "type": "integer", "minimum": 1 }, "holder_label": { "type": "string" }, "loan_count": { "type": "integer", "minimum": 1 }, "outstanding_balance_cents": { "type": ["integer", "null"], "minimum": 0 }, "request_method": { "type": ["string", "null"], "enum": ["online_portal", "phone", "mail", "fax", "email", "other", null] }, "request_status": { "type": ["string", "null"], "enum": ["not_started", "contacted_holder", "submitted", "additional_information_requested", "under_review", null] }, "submitted_on": { "type": ["string", "null"], "format": "date" }, "decision_status": { "type": ["string", "null"], "enum": ["not_received", "approved", "approved_with_different_terms", "denied", "withdrawn", null] }, "decision_received_on": { "type": ["string", "null"], "format": "date" }, "approved_plan_id": { "type": ["string", "null"], "enum": ["ffel_standard", "ffel_graduated", "ffel_income_sensitive", "ffel_extended_fixed", "ffel_extended_graduated", "other_holder_schedule", null] }, "approved_monthly_payment_cents": { "type": ["integer", "null"], "minimum": 1 }, "approved_payment_effective_on": { "type": ["string", "null"], "format": "date" }, "annual_review_due_on": { "type": ["string", "null"], "format": "date" }, "income_evidence_status": { "type": ["string", "null"], "enum": ["not_requested", "requested_will_provide_to_holder", "requested_attach_to_package", "provided_to_holder", null] }, "confirmation_reference_present": { "type": "boolean", "description": "True when an encrypted private confirmation reference exists. The reference value is never returned." }, "saved_field_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "AttachmentCollectionData": { "type": "object", "required": [ "attachment_manifest", "workflow" ], "properties": { "attachment": { "$ref": "#/components/schemas/OfficialFormAttachmentMetadata" }, "attachment_manifest": { "$ref": "#/components/schemas/OfficialFormAttachmentManifest" }, "deleted_attachment_id": { "type": "string" }, "workflow": { "$ref": "#/components/schemas/AnalysisWorkflowSummary" } }, "additionalProperties": false }, "OfficialFormAttachmentDocumentRole": { "type": "string", "enum": [ "borrower_tax_return_or_transcript", "joint_tax_return_or_transcript", "borrower_current_income", "spouse_current_income", "other_income_documentation", "tpd_va_disability_determination", "tpd_ssa_disability_documentation", "school_closure_exceptional_circumstances_evidence", "unpaid_refund_school_documentation", "false_certification_disqualifying_status_evidence", "false_certification_state_requirement_documentation", "false_certification_school_notification_evidence", "false_certification_program_access_denial_evidence", "false_certification_employment_denial_evidence", "false_certification_high_school_status_evidence", "false_certification_high_school_ged_documentation", "false_certification_high_school_ability_to_benefit_evidence", "false_certification_high_school_witness_statement", "false_certification_identity_theft_court_determination", "false_certification_identity_theft_ftc_affidavit", "false_certification_identity_theft_police_report", "false_certification_identity_theft_credit_bureau_disputes", "false_certification_identity_theft_other_evidence", "false_certification_identity_theft_cost_of_attendance_documentation", "false_certification_unauthorized_signature_samples", "false_certification_unauthorized_loan_documentation", "false_certification_unauthorized_payment_records", "false_certification_unauthorized_other_evidence", "forgery_correct_name_documentation", "forgery_correct_ssn_documentation", "forgery_correct_date_of_birth_documentation", "forgery_correct_address_documentation", "forgery_correct_references_documentation", "forgery_correct_other_information_documentation", "forgery_signature_samples", "forgery_court_verdict_or_judgment", "forgery_government_identification", "forgery_handwriting_expert_statement", "forgery_residency_documentation", "forgery_ftc_identity_theft_affidavit", "forgery_other_evidence", "forgery_contact_history_documentation", "forgery_cost_of_attendance_documentation", "forgery_police_report_or_official_complaint", "forgery_additional_supporting_documentation", "general_forbearance_supporting_documentation", "economic_hardship_existing_deferment_documentation", "economic_hardship_public_assistance_documentation", "economic_hardship_peace_corps_service_documentation", "economic_hardship_income_documentation", "unemployment_benefits_documentation", "unemployment_job_search_documentation", "unemployment_employment_agency_registration", "debt_burden_income_documentation", "debt_burden_title_iv_payment_documentation", "in_school_enrollment_verification_documentation", "parent_plus_enrollment_verification_documentation", "graduate_fellowship_program_certification_documentation", "rehabilitation_training_program_certification_documentation", "cancer_treatment_physician_certification_documentation", "military_service_commanding_or_personnel_officer_statement", "military_service_orders", "mandatory_forbearance_state_licensing_agency_statement", "mandatory_forbearance_authorized_official_documentation", "mandatory_forbearance_military_orders", "loan_rehabilitation_income_documentation", "loan_rehabilitation_expense_documentation", "direct_alternative_requested_evidence", "ffel_holder_requested_income_documentation" ] }, "OfficialFormAttachmentMetadata": { "type": "object", "required": [ "attachment_version", "attachment_id", "analysis_id", "document_package_id", "source_id", "requirement_id", "document_role", "file_name", "content_type", "byte_length", "content_sha256", "content_validation_status", "status", "uploaded_at", "uploaded_by" ], "properties": { "attachment_version": { "type": "string" }, "attachment_id": { "type": "string" }, "analysis_id": { "type": "string" }, "document_package_id": { "type": "string" }, "source_id": { "type": "string" }, "requirement_id": { "type": "string", "enum": [ "idr_current_income_documentation", "tpd_supporting_documentation", "school_discharge_supporting_documentation", "general_forbearance_supporting_documentation", "economic_hardship_supporting_documentation", "unemployment_supporting_documentation", "student_loan_debt_burden_supporting_documentation", "in_school_enrollment_verification_documentation", "parent_plus_enrollment_verification_documentation", "graduate_fellowship_program_certification_documentation", "rehabilitation_training_program_certification_documentation", "cancer_treatment_physician_certification_documentation", "military_service_eligibility_documentation", "mandatory_forbearance_supporting_documentation", "loan_rehabilitation_supporting_documentation", "direct_alternative_supporting_documentation", "ffel_holder_supporting_documentation" ] }, "document_role": { "$ref": "#/components/schemas/OfficialFormAttachmentDocumentRole" }, "file_name": { "type": "string", "maxLength": 160 }, "content_type": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "byte_length": { "type": "integer", "minimum": 1, "maximum": 10485760 }, "content_sha256": { "type": "string" }, "content_validation_status": { "type": "string", "enum": [ "signature_verified" ] }, "status": { "type": "string", "enum": [ "available", "deleted" ] }, "uploaded_at": { "type": "string", "format": "date-time" }, "uploaded_by": { "type": "string", "enum": [ "borrower", "partner" ] }, "deleted_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "OfficialFormAttachmentManifest": { "type": "object", "required": [ "manifest_version", "source_id", "requirement_id", "declared_documentation_status", "readiness_status", "required_document_roles", "optional_document_roles", "available_document_roles", "missing_document_roles", "attachments", "notes" ], "properties": { "manifest_version": { "type": "string" }, "source_id": { "type": "string" }, "requirement_id": { "type": "string", "enum": [ "idr_current_income_documentation", "tpd_supporting_documentation", "school_discharge_supporting_documentation", "general_forbearance_supporting_documentation", "economic_hardship_supporting_documentation", "unemployment_supporting_documentation", "student_loan_debt_burden_supporting_documentation", "in_school_enrollment_verification_documentation", "parent_plus_enrollment_verification_documentation", "graduate_fellowship_program_certification_documentation", "rehabilitation_training_program_certification_documentation", "cancer_treatment_physician_certification_documentation", "military_service_eligibility_documentation", "mandatory_forbearance_supporting_documentation", "loan_rehabilitation_supporting_documentation", "direct_alternative_supporting_documentation", "ffel_holder_supporting_documentation" ] }, "declared_documentation_status": { "type": [ "string", "null" ], "enum": [ "attached", "not_required", "will_provide_to_servicer", null ] }, "readiness_status": { "type": "string", "enum": [ "pending_income_branch", "pending_documentation_path", "not_required", "missing_required_attachments", "ready" ] }, "required_document_roles": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialFormAttachmentDocumentRole" } }, "optional_document_roles": { "type": "array", "description": "Branch-specific records accepted in the final package but not required for readiness.", "items": { "$ref": "#/components/schemas/OfficialFormAttachmentDocumentRole" } }, "available_document_roles": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialFormAttachmentDocumentRole" } }, "missing_document_roles": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialFormAttachmentDocumentRole" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialFormAttachmentMetadata" } }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "DocumentBundleData": { "type": "object", "required": [ "document_bundle", "document_bundle_download", "workflow" ], "properties": { "document_bundle": { "$ref": "#/components/schemas/DocumentBundle" }, "document_bundle_download": { "$ref": "#/components/schemas/DocumentBundleDownloadMetadata" }, "workflow": { "$ref": "#/components/schemas/AnalysisWorkflowSummary" } }, "additionalProperties": false }, "DocumentBundleDownloadMetadata": { "type": "object", "required": [ "download_url", "file_name", "content_type" ], "properties": { "download_url": { "type": "string", "description": "Protected relative URL for the generated bundle archive." }, "file_name": { "type": "string" }, "content_type": { "type": "string", "enum": [ "application/zip" ] } }, "additionalProperties": false }, "AnalysisWorkflowSummary": { "type": "object", "required": [ "workflow_version", "analysis_id", "channel", "active_stage", "next_action_ids", "plan_options", "document_packages", "blocked_reasons" ], "properties": { "workflow_version": { "type": "string" }, "analysis_id": { "type": "string" }, "channel": { "type": "string", "enum": [ "b2b" ] }, "active_stage": { "$ref": "#/components/schemas/WorkflowStage" }, "next_action_ids": { "type": "array", "items": { "type": "string" } }, "plan_options": { "type": "array", "items": { "$ref": "#/components/schemas/RepaymentWorkflowPlanOption" } }, "document_packages": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentPackageWorkflowSummary" } }, "active_document_package_id": { "type": "string" }, "blocked_reasons": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "DocumentPackageWorkflowSummary": { "type": "object", "required": [ "document_package_id", "selected_plan_id", "required_official_form_source_ids", "supplemental_intake_source_ids" ], "properties": { "document_package_id": { "type": "string" }, "analysis_scenario_id": { "type": "string" }, "selected_plan_id": { "type": "string" }, "required_official_form_source_ids": { "type": "array", "description": "Backend-selected official-form sources required by this package, in generation order.", "items": { "type": "string" } }, "supplemental_intake_source_ids": { "type": "array", "description": "Backend-selected sources that accept supplemental intake for this package. This includes required official forms and optional guidance intake such as Direct Alternative.", "items": { "type": "string" } } }, "additionalProperties": true }, "WorkflowStage": { "type": "string", "enum": [ "plan_selection_ready", "supplemental_intake_needed", "borrower_attestation_needed", "income_documentation_needed", "document_review_needed", "manual_review_needed", "ready_to_generate_bundle", "blocked" ] }, "RepaymentWorkflowPlanOption": { "type": "object", "required": [ "plan_id", "selectable" ], "properties": { "analysis_scenario_id": { "type": "string", "description": "Present when this option belongs to a saved what-if scenario. Return it when creating the document package." }, "scenario_type": { "type": "string", "enum": [ "new_direct_consolidation" ] }, "plan_id": { "type": "string", "description": "Effective-dated server decision. Current plan IDs may include direct_standard, direct_graduated, direct_extended_fixed, direct_extended_graduated, direct_alternative, tiered_standard, direct_ibr, paye, icr, rap, ffel_standard, ffel_graduated, ffel_income_sensitive, ffel_extended_fixed, ffel_extended_graduated, ffel_ibr, or perkins_institution. Direct Alternative is selectable with document_preparation_status review_required, quote_status requires_input, and no monthly_payment_cents because the Secretary must approve exceptional circumstances and issue written terms. FFEL Income-Sensitive remains non-selectable until the holder provides its schedule." }, "rank": { "type": "integer", "minimum": 1 }, "recommendation_status": { "type": "string" }, "document_preparation_status": { "type": "string" }, "monthly_payment_cents": { "type": "integer", "minimum": 0 }, "selectable": { "type": "boolean" }, "blocked_reasons": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "DocumentPackage": { "type": "object", "required": [ "analysis_id", "document_package_id", "selected_plan_id", "package_status", "review" ], "properties": { "analysis_id": { "type": "string" }, "document_package_id": { "type": "string" }, "analysis_scenario_id": { "type": "string" }, "selected_plan_id": { "type": "string" }, "package_status": { "type": "string" }, "review": { "$ref": "#/components/schemas/DocumentPackageReview" }, "document_loan_selection": { "$ref": "#/components/schemas/DocumentLoanSelection" }, "document_qualification": { "$ref": "#/components/schemas/DocumentQualificationSnapshot" } }, "additionalProperties": true }, "DocumentQualificationSnapshot": { "type": "object", "required": [ "qualification_version", "catalog_version", "evaluated_at", "screening_complete", "candidates", "summary", "disclaimer" ], "properties": { "qualification_version": { "type": "string" }, "catalog_version": { "type": "string" }, "evaluated_at": { "type": "string", "format": "date-time" }, "screening_complete": { "type": "boolean" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentFormCandidate" } }, "summary": { "type": "object", "properties": { "potential_match_count": { "type": "integer", "minimum": 0 }, "needs_more_information_count": { "type": "integer", "minimum": 0 }, "not_indicated_count": { "type": "integer", "minimum": 0 }, "third_party_certification_candidate_count": { "type": "integer", "minimum": 0 }, "required_companion_document_count": { "type": "integer", "minimum": 0 }, "companion_follow_up_count": { "type": "integer", "minimum": 0 }, "pending_companion_audit_count": { "type": "integer", "minimum": 0 }, "total_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "disclaimer": { "type": "string" } }, "additionalProperties": false }, "DocumentFormCandidate": { "type": "object", "required": [ "form_id", "source_id", "title", "program_area", "candidate_status", "reason", "lifecycle_status", "preparation_support", "follow_up_field_ids", "certification_requirements", "companion_audit_status", "companion_documents", "submission_destination" ], "properties": { "form_id": { "type": "string" }, "source_id": { "type": "string" }, "title": { "type": "string" }, "program_area": { "type": "string", "enum": [ "repayment", "consolidation", "forgiveness", "discharge", "deferment", "forbearance", "default_resolution", "military_benefit", "loan_administration", "institution_administered" ] }, "candidate_status": { "type": "string", "enum": [ "potential_match", "needs_more_information", "not_indicated" ] }, "reason": { "type": "string" }, "lifecycle_status": { "type": "string", "enum": [ "active", "online_only", "pending_release", "servicer_specific", "institution_specific", "superseded" ] }, "preparation_support": { "type": "string", "enum": [ "prefill_available", "prefill_planned", "instructions_only" ] }, "matched_screening_field_ids": { "type": "array", "items": { "type": "string" } }, "unanswered_screening_field_ids": { "type": "array", "items": { "type": "string" } }, "follow_up_field_ids": { "type": "array", "items": { "type": "string" } }, "certification_requirements": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentCertificationRequirement" } }, "companion_audit_status": { "type": "string", "enum": [ "verified_none", "verified_requirements", "pending_review" ] }, "companion_documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentCompanionEvaluation" } }, "submission_destination": { "type": "object", "required": [ "destination_type", "label", "instructions" ], "properties": { "destination_type": { "type": "string", "enum": [ "loan_holder_or_servicer", "federal_student_aid", "dedicated_federal_processor", "school_or_institution", "online_portal" ] }, "label": { "type": "string" }, "instructions": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "DocumentCompanionEvaluation": { "type": "object", "required": [ "companion_id", "title", "relationship_type", "trigger", "generation_strategy", "submission_timing", "required_identifying_field_ids", "instructions", "status", "reason" ], "properties": { "companion_id": { "type": "string" }, "title": { "type": "string" }, "relationship_type": { "type": "string", "enum": [ "continuation_sheet", "required_companion_form", "post_submission_form", "supporting_document" ] }, "linked_form_id": { "type": "string" }, "trigger": { "oneOf": [ { "type": "object", "required": [ "trigger_type" ], "properties": { "trigger_type": { "const": "always" } }, "additionalProperties": false }, { "type": "object", "required": [ "trigger_type", "selected_plan_ids" ], "properties": { "trigger_type": { "const": "selected_plan" }, "selected_plan_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, { "type": "object", "required": [ "trigger_type", "count_source", "primary_capacity", "rows_per_companion" ], "properties": { "trigger_type": { "const": "row_capacity_exceeded" }, "count_source": { "type": "string", "enum": [ "selected_consolidation_loans", "excluded_consolidation_loans", "loans_to_add" ] }, "primary_capacity": { "type": "integer", "minimum": 1 }, "rows_per_companion": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, { "type": "object", "required": [ "trigger_type", "follow_up_field_ids" ], "properties": { "trigger_type": { "const": "conditional_follow_up" }, "follow_up_field_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ] }, "generation_strategy": { "type": "string", "enum": [ "generated_continuation_sheet", "separate_official_form", "borrower_attachment", "instructions_only" ] }, "submission_timing": { "type": "string", "enum": [ "with_primary_form", "after_primary_submission", "separate_submission" ] }, "required_identifying_field_ids": { "type": "array", "items": { "type": "string" } }, "instructions": { "type": "string" }, "status": { "type": "string", "enum": [ "required", "not_required", "needs_more_information", "not_applicable" ] }, "reason": { "type": "string" }, "source_item_count": { "type": "integer", "minimum": 0 }, "possible_source_item_count": { "type": "integer", "minimum": 0 }, "required_document_count": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "DocumentCertificationRequirement": { "type": "object", "required": [ "certification_id", "signer_role", "required", "form_section", "handoff_title", "instructions", "acceptable_alternatives", "signature_required", "signer_completes_fields" ], "properties": { "certification_id": { "type": "string" }, "signer_role": { "type": "string", "enum": [ "borrower", "spouse", "co_borrower", "employer_authorized_official", "school_authorized_official", "medical_professional", "military_authorized_official", "program_authorized_official" ] }, "required": { "type": "string", "enum": [ "always", "conditional" ] }, "form_section": { "type": "string" }, "handoff_title": { "type": "string" }, "instructions": { "type": "string" }, "acceptable_alternatives": { "type": "array", "items": { "type": "string" } }, "signature_required": { "type": "boolean" }, "signer_completes_fields": { "type": "boolean" } }, "additionalProperties": false }, "DocumentBundle": { "type": "object", "required": [ "bundle_id", "bundle_status", "document_package_id", "artifacts", "official_forms", "warnings" ], "properties": { "bundle_id": { "type": "string" }, "bundle_status": { "type": "string", "enum": [ "ready" ] }, "document_package_id": { "type": "string" }, "analysis_id": { "type": "string" }, "selected_plan_id": { "type": "string" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBundleArtifact" } }, "official_forms": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedOfficialFormMetadata" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "DocumentBundleArtifact": { "type": "object", "required": [ "artifact_id", "artifact_kind", "title", "file_name", "content_type", "content_sha256" ], "properties": { "artifact_id": { "type": "string" }, "artifact_kind": { "type": "string", "enum": [ "document_packet_json", "borrower_review_summary", "official_form_population_plan", "official_form_readiness_report", "official_form_attachment_manifest", "official_source_inventory", "servicer_submission_checklist", "document_path_review", "certification_handoff_guide", "ffel_holder_repayment_tracker" ] }, "title": { "type": "string" }, "file_name": { "type": "string" }, "content_type": { "type": "string", "enum": [ "application/json", "text/markdown" ] }, "content_sha256": { "type": "string" }, "source_trace_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "GeneratedOfficialFormMetadata": { "type": "object", "required": [ "source_id", "title", "file_name", "content_type", "completion_status", "byte_length", "content_sha256", "template_version", "template_sha256", "filled_field_count", "requires_borrower_signature", "supporting_documents_included" ], "properties": { "source_id": { "type": "string" }, "form_instance_id": { "type": "string", "description": "Stable identifier for one generated PDF when a source produces multiple forms, such as a PSLF employment period or Teacher Loan Forgiveness holder-specific copy." }, "title": { "type": "string" }, "file_name": { "type": "string" }, "content_type": { "type": "string", "enum": [ "application/pdf" ] }, "completion_status": { "type": "string", "enum": [ "signature_required" ] }, "byte_length": { "type": "integer", "minimum": 1 }, "content_sha256": { "type": "string" }, "template_version": { "type": "string" }, "template_sha256": { "type": "string" }, "filled_field_count": { "type": "integer", "minimum": 1 }, "requires_borrower_signature": { "type": "boolean", "enum": [ true ] }, "required_third_party_certifier_roles": { "type": "array", "items": { "type": "string" }, "description": "Third-party roles that must complete the remaining certification fields after RepayIQ prefill." }, "supporting_documents_included": { "type": "boolean", "enum": [ false ] } }, "additionalProperties": false }, "DocumentPackageReview": { "type": "object", "required": [ "review_status", "required_field_ids", "reviewed_field_ids" ], "properties": { "review_status": { "type": "string", "enum": [ "not_started", "in_progress", "completed" ] }, "required_field_ids": { "type": "array", "items": { "type": "string" } }, "reviewed_field_ids": { "type": "array", "items": { "type": "string" } }, "reviewed_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } }