Credora APIs

Mock external APIs#

All three are FastAPI services. Every /v1/* call needs the header X-API-Key: <MOCK_API_TOKEN>; a missing or wrong key gets 401 {"detail":"missing or invalid X-API-Key"}. Each service also serves GET /health (no key) and an OpenAPI page at /docs. Before the first generation, or while the mock database is down, data endpoints and /status return 503.

Bulk endpoints take up to 5,000 keys per call; duplicates are ignored and results follow the request order. Exasol UDFs should prefer them (one call per few hundred keys) to thousands of single calls.

Exasol reaches them on the app host's private IP at ports 8101–8103 (open to the VPC only).

Mock CIBIL#

GET /v1/consumer/{pan}

{"pan":"ABCPM1234K","name":"Rohit Mehta","dob":"1979-04-12","score":782,"report_date":"2026-10-31",
 "enquiries_6m":1,"enquiries_12m":2,
 "accounts":[{"lender":"HDFC Bank","acct_type":"Home Loan","opened_on":"2018-06-01","sanctioned":4500000.0,
              "balance":2100000.0,"overdue":0.0,"status":"ACTIVE","dpd_36m":[0,0,0,30,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}]}

404 if the PAN is unknown.

GET /v1/commercial/{pan}

{"pan":"AAACS1234K","name":"Shree Ganesh Polymers Pvt Ltd","cmr_rank":3,"report_date":"2026-10-31",
 "total_exposure":32000000.0,"overdue":0.0,"suit_filed":false,"wilful_default":false,"facilities":4}

POST /v1/consumer/bulk body {"pans":["ABCPM1234K", ...]}

{"reports":[{...same shape as GET /v1/consumer/{pan}...}],"not_found":["ZZZZZ9999Z"]}

POST /v1/commercial/bulk body {"pans":[...]} returns {"reports":[{...same shape as GET /v1/commercial/{pan}...}],"not_found":[...]}

GET /status (no key): {"generated_at":"...","seed":123,"consumer_reports":3511,"commercial_reports":1000}

Mock GSTN#

GET /v1/gstin/{gstin}

{"gstin":"27AAACS1234K1Z5","legal_name":"Shree Ganesh Polymers Pvt Ltd","pan":"AAACS1234K","state":"Maharashtra",
 "registered_on":"2019-04-01","status":"ACTIVE","years_of_filing":7.5,"stage":"Mid-level"}

GET /v1/gstin/{gstin}/returns?from=YYYY-MM&to=YYYY-MM (default: all)

{"gstin":"27AAACS1234K1Z5","returns":[{"period":"2026-09","gstr1_turnover":5230000.0,"gstr3b_tax_paid":941400.0,
 "due_date":"2026-10-20","filed_on":"2026-10-18","delay_days":0}]}

Returns are newest first. For a return that was not filed, filed_on, delay_days, gstr1_turnover and gstr3b_tax_paid are null. delay_days = max(0, filed_on − due_date). years_of_filing = number of periods / 12; stage is New below 5 years, Mid-level below 8, else Stable. 404 if the GSTIN is unknown; 422 if from or to is not YYYY-MM.

POST /v1/returns/bulk body {"gstins":[...], "from":"YYYY-MM", "to":"YYYY-MM"} (from and to optional)

{"items":[{"gstin":"27AAACS1234K1Z5","registration":{...same shape as GET /v1/gstin/{gstin}...},
           "returns":[{...same shape as above...}]}],"not_found":[...]}

GET /status (no key): {"generated_at":"...","registrations":1000,"filings":61234}

Mock Account Aggregator#

POST /v1/consent body {"pan":"ABCPM1234K","purpose":"Loan underwriting"}

{"consent_id":"7a1c...","pan":"ABCPM1234K","status":"ACTIVE","created_at":"...","expires_at":"..."}

Consent is approved at once (the mock customer always says yes). It expires after 24 hours.

GET /v1/fi/{consent_id}

{"consent_id":"7a1c...","pan":"ABCPM1234K","accounts":[
  {"aa_account_id":"AA00000123","fip":"HDFC Bank","acct_type":"SAVINGS","masked_no":"XXXXXX4521",
   "opened_on":"2015-02-11","current_balance":412500.0,
   "transactions":[{"txn_date":"2026-10-28","dr_cr":"C","amount":85000.0,"narration":"SALARY/NEFT","balance_after":412500.0}]}]}

Accounts are ordered by id; transactions are newest first. 404 if the consent id is unknown, 403 if the consent expired. A PAN with no other-bank accounts still gets a consent, with an empty accounts list.

POST /v1/fi/bulk body {"pans":[...], "purpose":"Loan underwriting"} (purpose optional). Creates one consent per PAN and returns the data at once:

{"items":[{"pan":"ABCPM1234K","consent_id":"7a1c...","accounts":[{...same shape as in GET /v1/fi/{consent_id}...}]}]}

GET /status (no key): {"generated_at":"...","seed":123,"accounts":5210,"transactions":412345,"consents":17}

Mock data generator (generator:8100, internal only)#

Steps: clear, synthesize, oracle, mysql, postgres, mockdb, truth_export. The same seed gives the same data on the same day (dates are relative to the generation date).

Credora backend API (/api, FastAPI)#

Login returns a bearer token. Each user has one role: admin, datasci, loanops or rm. Every response that carries data includes a source field naming where it came from:

Backend response shapes#

The shapes follow frontend/src/api/types.ts; where this document and types.ts differed, types.ts won. Reads for a signed-in person run as that role's Exasol user (CREDORA_ADMIN, CREDORA_DATASCI, CREDORA_LOANOPS, CREDORA_RM), so Exasol enforces access; a query Exasol refuses comes back as 403 {"detail":"Exasol denied access for your role: ..."}. Analysis, training, the CRM export, model activation and the purge run as CREDORA_SVC. Times are ISO 8601 in UTC (...Z). Errors are {"detail": "..."}.

Sign-in. POST /api/auth/login returns {token, user:{username, role, display_name, rm_id?}}. The token is an HS256 JWT signed with APP_SECRET, valid 12 hours; send it as Authorization: Bearer <token>. Usernames are the role names. The rm login acts as one relationship manager, APP_RM_ID (default RM001), and sees only companies and offers whose rm_id matches.

Current run. Lists and reports use the newest analysis run that finished without a failed step and after the last data generation (GET generator/last). Until analysis runs on fresh data, reports return 404 and decision fields are null.

CRM export. After each successful analysis run, offers are upserted by app_id: rows at OFFERED or DECLINED take the new run's terms (APPROVE and REFER become OFFERED, DECLINE becomes DECLINED) and keep their offer_id. Rows at NEGOTIATING, ESCALATED, VERIFIED or SANCTIONED keep their state. If the CRM is empty when offers are first listed, the current run is exported then. The backend adds legal_name and rm_id columns to crm.offer and creates crm.audit_event.

Backend environment. The runtime secret keys (APP_SECRET, APP_*_PASSWORD, EXASOL_HOST, EXASOL_PORT, EXA_*_PASSWORD, PG_HOST, PG_PORT, PG_USER, PG_PASSWORD, MOCK_API_TOKEN, AI_PROVIDER, AI_MODEL, ANTHROPIC_API_KEY, EXA_MCP_PASSWORD), plus GENERATOR_URL, MOCK_CIBIL_URL, MOCK_GSTN_URL, MOCK_AA_URL from compose. Optional: APP_RM_ID (RM001), PG_CRM_DB (crm), PG_SSLMODE (require), EXA_POOL_SIZE (3), TOKEN_HOURS (12), PURGE_INTERVAL_MIN (15), AWS_REGION (for AI_PROVIDER=bedrock), MCP_SERVER_CMD (command that starts the Exasol MCP server; default exasol-mcp-server on PATH, as in the Docker image, else uvx exasol-mcp-server@2.3.0).